forked from sugarlabs/musicblocks
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
338 lines (338 loc) · 21.5 KB
/
index.html
File metadata and controls
338 lines (338 loc) · 21.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" integrity="sha384-1q8mTJOASx8j1Au+a5WDVnPi2lkFfwwEAa8hDDdjZlpLegxhjVME1fgjWPGmkzs7" crossorigin="anonymous">
<style type="text/css">
ol { counter-reset: item }
li { display: block }
li:before { content: counters(item, ".") " "; counter-increment: item }
</style>
</head>
<body>
<div class="container">
<div id="content">
<h1 id="using-music-blocks">Using Music Blocks</h1>
<p>Music Blocks is a fork of <a href="https://turtle.sugarlabs.org">Turtle Blocks</a>. It has extensions for
exploring music: pitch and rhythm.</p>
<p>Music Blocks is designed to run in a browser. Most of the development
has been done in Chrome. </p>
<table>
<thead>
<tr>
<th>Browser</th>
<th>Comments</th>
</tr>
</thead>
<tbody>
<tr>
<td>Chrome</td>
<td>Supported</td>
</tr>
<tr>
<td>Safari</td>
<td>Supported</td>
</tr>
<tr>
<td>Firefox</td>
<td>Supported</td>
</tr>
<tr>
<td>Opera</td>
<td>Supported</td>
</tr>
<tr>
<td>Internet Explorer</td>
<td>Not Supported</td>
</tr>
</tbody>
</table>
<p>You can run from <a href="https://musicblocks.sugarlabs.org">https://musicblocks.sugarlabs.org</a>.</p>
<p><img src="getting-started.png" alt="getting-started.png" title="Music Blocks in a browser" width="100%"></p>
<h2 id="getting-started">Getting Started</h2>
<p><img src="default_block.svg" alt="default_block.svg" title="default blocks"></p>
<p>When you first launch Music Blocks in your browser, you'll see a stack
of blocks representing three notes: <code>Sol 4</code>, <code>Mi 4</code>, and <code>Sol 2</code>. The
first two notes are <code>1/4</code> notes; the third note is a <code>1/2</code> note.</p>
<p>Try clicking on the <em>Start</em> block or click on the <em>Play</em> button. You should hear the notes play in succession: <code>Sol</code> <code>Mi</code> <code>Sol</code>.</p>
<p>To write your own programs, drag blocks from their respective palettes
on the left side of the screen. Use multiple blocks in stack(s) to
create music and drawings; as the mouse moves under your control,
colorful lines are drawn and music of your creation is played.</p>
<p>Note that blocks either snap together vertically or
horizontally. Vertical connections indicate program (and temporal)
flow. Code is executed from the top to bottom of a stack of
blocks. Horizontal connections are used for parameters and arguments,
e.g., the name of a pitch, the duration of a note, the numerator and
denominator of a division. From the shape of the block, it should be
apparent whether they connect vertically or horizontally.</p>
<p>Some blocks, referred to as "clamp" blocks have an
interior—child—flow. This might be code that is run <em>if</em> a
condition is true, or, more common, the code that is run over the
duration of a note.</p>
<p>For the most part, any combination of blocks will run (although there
is no guarantee that they will produce music). Illegal combinations
of blocks will be flag by a warning on the screen as the program runs.</p>
<p>You can delete a block by dragging it back into the trash area that
appear at the bottom of the screen.</p>
<p>To maximize screen real estate, Music Blocks overlays the program
elements (stacks of blocks) on top of the canvas. These blocks can be
hidden at any time while running the program.</p>
<h2 id="toolbars">Toolbars</h2>
<p>There are three toolbars:</p>
<p>(1) the <em>Main</em> toolbar across the top of the screen. There you will
find the <em>Run</em> button, the <em>Erase</em> button, and buttons to <em>Hide</em> and
<em>Show</em> blocks.</p>
<p>(2) the <em>Secondary</em> toolbar on the right side of the screen. There you
will find buttons for loading and saving projects, the clipboard,
etc. There is also a utility panel with additional controls.</p>
<p>(3) the <em>Palette</em> toolbar on the left side of the screen. (An
additional menu appears when a "long press" is applied to a stack of
blocks).</p>
<p>These toolbars are described in detail in the
<a href="http://github.com/sugarlabs/turtleblocksjs/tree/master/documentation">Turtle Blocks documentation pages</a>.</p>
<h2 id="keyboard-shortcuts">Keyboard shortcuts</h2>
<p>There are several keyboard shortcuts:</p>
<p><em>PgUp</em> and <em>PgDn</em> will scroll the screen vertically. This is useful for
creating long stacks of blocks.</p>
<p>You can use the arrow keys to move blocks and the <em>Delete</em> key to
remove an individual block from a stack.</p>
<p><em>Enter</em> is the equivalent of clicking the <em>Run</em> button.</p>
<p><em>Alt-C</em> is copy and <em>Alt-V</em> is paste. Be sure that the cursor is
highlighting the block(s) you want to copy.</p>
<p>You can directly type notes using <em>d</em> for <code>Do</code>, <em>r</em> for <code>Re</code>, <em>m</em> for
<code>Mi</code>, <em>f</em> for <code>Fa</code>, <em>s</em> for <code>Sol</code>, <em>l</em> for <code>La</code>, and <em>t</em> for <code>Ti</code>.</p>
<h2 id="block-palettes">Block Palettes</h2>
<p>The block palettes are displayed on the left side of the screen. These
palettes contain the blocks used to create programs.</p>
<p>See the
<a href="http://github.com/sugarlabs/turtleblocksjs/tree/master/guide/README.md">Turtle Blocks Programming Guide</a>
for general details on how to use the blocks. </p>
<p>See the
<a href="http://github.com/sugarlabs/musicblocks/tree/master/guide/README.md">Music Blocks Programming Guide</a>
for details specific to music: <em>Rhythm</em>, <em>Pitch</em>, <em>Meter</em>, <em>Tone</em>,
<em>Intervals</em>, <em>Volume</em>, <em>Drum</em>, and <em>Widget</em>.</p>
<p>All of the other palettes are described in the
<a href="http://github.com/sugarlabs/turtleblocksjs/tree/master/documentation">Turtle Blocks documentation pages</a>.</p>
<h2 id="defining-a-note">Defining a note</h2>
<p><img src="notecounter_block.svg" alt="notecounter_block.svg" title="the note"></p>
<p>At the heart of Music Blocks is the concept of a note. A note, defined
by the <em>Note value</em> block defines a length of time and a set of
actions to occur in that time. Typically the action is to play a
pitch, or series of pitches (e.g., a chord). Whatever blocks are placed
inside the "clamp" of a <em>Note value</em> block are played over the
duration of the note.</p>
<p>The duration of a note is determined by its note value. By default, we
use musical notation, referring to whole notes (<code>1</code>), half notes
(<code>1/2</code>), quarter notes (<code>1/4</code>), etc., but you can use any number as
the note duration. (There are some practical limitations, which you
can discover through experimentation.) The relative length of a
quarter note is half as long as a half note. By default, Music Blocks
will play 90 quarter notes per second, so each quarter note is <code>2/3</code>
seconds (<code>666</code> microseconds) in duration.</p>
<p><img src="pitch_block.svg" alt="pitch_block.svg" title="Pitch block"></p>
<p>The <em>Pitch</em> block (found on the Pitch Palette) is used to specify the
pitch of a note. By default, we use traditional western Solfege, i.e.,
<code>Do</code>, <code>Re</code>, <code>Mi</code>, <code>Fa</code>, <code>Sol</code>, <code>La</code>, <code>Ti</code>, where <code>Do</code> is mapped to
<code>C</code>, <code>Re</code> is mapped to <code>D</code>, etc. (when the key and mode are <code>C
Major</code>). You can also specify pitch by using a note name, e.g.,
<code>F#</code>. An octave specification is also required (as an argument for our
pitch block) and changes integers for every cycle of <code>C</code> (i.e. <code>C4</code> is
higher than B3). When used with the <em>Pitch-time Matrix</em> block, a row
is created for each <em>Pitch</em> block.</p>
<p>In addition to specifying the note name, you must also specify an
octave. The frequency of a note doubles as the octave increases. <code>A2</code> is
<code>110 Hertz</code>; <code>A3</code> is <code>220 Hertz</code>; <code>A4</code> is <code>440 Hertz</code>; etc.</p>
<p><img src="solfege_block.svg" alt="solfege_block.svg" title="Solfege block"></p>
<p><img src="pitchdrummatrix_block.svg" alt="pitchdrummatrix_block.svg" title="Pitch-Name block"></p>
<p>Two special blocks can be used with a <em>Pitch</em> block to specify the
name of the pitch: the <em>Solfege</em> block and the <em>Pitch-Name</em> block. The
<em>Solfege</em> block uses selectors to scroll through <code>Do</code>, <code>Re</code>, <code>Mi</code>,
<code>Fa</code>, <code>Sol</code>, <code>La</code>, and <code>Ti</code>. A second selector is used for sharps and
flats: <code>##</code>, <code>#</code>, <code>and</code>. The <em>Pitch-Name</em> block is similar
in that it lets you scroll through <code>C</code>, <code>D</code>, <code>E</code>, <code>F</code>, <code>G</code>, <code>A</code>,
<code>B</code>. It also uses a second selector for sharps and flats.</p>
<p>As noted, and described in more detail in the
<a href="http://github.com/sugarlabs/musicblocks/tree/master/guide/README.md">Music Blocks Programming Guide</a>,
you can put as many <em>Pitch</em> blocks inside a note as you'd like. They
will play together as a chord. You can also insert graphics blocks
inside a note in order to create sound-sync animations.</p>
<h2 id="a-quick-tour-of-selected-blocks">A quick tour of selected blocks</h2>
<p><img src="settimbre_block.svg" alt="settimbre_block.svg" title="Set timbre block"></p>
<p>The <em>Set timbre</em> block, found on the <em>Tone</em> palette, lets you choose a
timbre for a note. In the above example, a guitar model is used to
make any notes contained within the block's clamp will sound as if
they are being played on a guitar.</p>
<p><img src="setsynthvolume_block.svg" alt="setsynthvolume_block.svg" title="Set synth volume"></p>
<p>The <em>Set synth volume</em> block, found on the <em>Volume</em> palette, lets you
change the volume, which ranges from <code>0</code> (silent) to <code>100</code> (full
volume), of any notes contained with the block's clamp.</p>
<p><img src="settimbre_block.svg" alt="settimbre_block.svg" title="Set drum block"></p>
<p>The <em>Set drum</em> block, which is used inside of the clamp of a <em>Note
value</em> block is used to add drum sounds to a note. It is found on the
<em>Drum</em> palette.</p>
<p><img src="repeat_block.svg" alt="repeat_block.svg" title="Repeat"></p>
<p>The <em>Repeat</em> block, found on the <em>Flow</em> palette, is used to create
loops. Whatever stack of blocks are placed inside its clamp will be
repeated. It can be used to repeat individual notes, or entire phrases
of music.</p>
<p><img src="duplicatenotes_block.svg" alt="duplicatenotes_block.svg" title="Duplicate block"></p>
<p>The <em>Duplicate</em> block, found on the <em>Rhythm</em> palette, is used to
repeat any contained notes. Similar to using a <em>Repeat</em> block, but
rather than repeating a sequence of notes multiple times, each note is
repeated in turn, e.g. duplicate x2 of <code>4 4 8</code> would result in <code>4 4 4
4 8 8</code>, where as repeat x2 of <code>4 4 8</code> would result in <code>4 4 8 4 4 8</code>.</p>
<p><img src="start_block.svg" alt="start_block.svg" title="Start"></p>
<p>The <em>Start</em> block, found on the <em>Action</em> palette, is tied to the <em>Run</em>
button. Anything inside of the clamp of the <em>Start</em> button will be run
when the button is pressed.</p>
<p>Note that you can have multiple mice and that each mouse is
equivalent to a "voice" in music. It can play notes of various pitches
in sequence, and can even play multiple notes of the same "note
value", but no one mouse can do counterpoint by itself—just like
one mouse cannot draw two lines at the same time. If you want
counterpoint, pull out an additional <em>Start</em> block, which will create
a new mouse that can now perform a new voice.</p>
<p><img src="action_block.svg" alt="action_block.svg" title="Action"></p>
<p><img src="time_block.svg" alt="time_block.svg" title="chunk"></p>
<p>The <em>Action</em> block, also found on the <em>Action</em> palette, is used to
create a collection of blocks that can be run as a group. Whenever you
create an <em>Action</em> block, a new block corresponding to that action is
added to the palette. The name given to the action is the name
associated with the new block. (It is common practice to use <em>Action</em>
blocks to define short phrases of music that can be repeated and
modified.)</p>
<p>Actions are a powerful organizational element for your program and can
be used in many powerful ways, e.g., an action can be associated with
an event, such as an on beat or off beat or mouse click. See
<a href="http://github.com/sugarlabs/musicblocks/tree/master/guide/README.md">Music Blocks Programming Guide</a>,
for further details and examples.</p>
<p><img src="storein_block.svg" alt="storein_block.svg" title="storein"></p>
<p><img src="box_block.svg" alt="box_block.svg" title="box"></p>
<p><img src="incrementOne_block.svg" alt="incrementOne_block.svg" title="add one"></p>
<p>The <em>Store in</em> block, found on the <em>Boxes</em> palette, is used to store a
value. That value can be retrieved using the <em>Box</em> block. The value
can be modified using the <em>Add one</em> block. These blocks are the
typical way in which variables are stored and retrieved in Music
Blocks.</p>
<p><img src="forward_block.svg" alt="forward_block.svg" title="forward"></p>
<p>The <em>Forward</em> block, found on the <em>Mouse</em> palette, is used to draw straight lines. (Note that if this block is used inside of a <em>Note value</em> block—the line will be drawn as the note plays; otherwise the line is drawn "instantly".)</p>
<p><img src="right_block.svg" alt="right_block.svg" title="right"></p>
<p>The <em>Right</em> block, found on the <em>Mouse</em> palette, is used to rotate the
mouse heading. (Note that if this block is used inside of a <em>Note
value</em> block—the heading will change as the note plays;
otherwise the heading is changed "instantly".)</p>
<p><img src="penup_block.svg" alt="penup_block.svg" title="pen up"></p>
<p><img src="pendown_block.svg" alt="pendown_block.svg" title="pen down"></p>
<p>The <em>Pen up</em> and <em>Pen down</em> blocks, found on the <em>Pen</em> palette,
determine whether or not the mouse draws as it moves.</p>
<p><img src="setshade_block.svg" alt="setshade_block.svg" title="set shade"></p>
<p>The <em>Set shade</em> block, also found on the <em>Pen</em> palette, is used to set
the lightness or darkness of the "ink" used in the mouse pen. <code>set
shade 0</code> is black. <code>set shade 100</code> is white.</p>
<p><img src="setcolor_block.svg" alt="setcolor_block.svg" title="set color"></p>
<p>The <em>Set color</em> block, also found on the <em>Pen</em> palette, is used to set
the color of the "ink" used in the mouse pen. <code>set color 0</code> is
red. <code>set color 70</code> is blue.</p>
<p><img src="random_block.svg" alt="random_block.svg" title="random"></p>
<p>The <em>Random</em> block, found on the <em>Number</em> palette, is used to
generate a random number, because sometimes being unpredictable is
nice.</p>
<p><img src="oneOf_block.svg" alt="oneOf_block.svg" title="on of this or that"></p>
<p>The <em>One of</em> block, also found on the <em>Number</em> palette, is used to
generate a binary choice, one of "this" or "that", because sometimes
being unpredictable is nice.</p>
<p><img src="show_block.svg" alt="show_block.svg" title="show media"></p>
<p>The <em>Show</em> block, found on the <em>Media</em> palette, is used to display
text and images.</p>
<p><img src="showblocks_block.svg" alt="showblocks_block.svg" title="shell"></p>
<p>The <em>Shell</em> block, also found on the <em>Media</em> palette, is used to
change the appearance of a mouse, which can then act like a "sprite"
in an animation.</p>
<p><img src="mousebutton_block.svg" alt="mousebutton_block.svg" title="mousebutton"></p>
<p>The <em>Mouse button</em> block, found on the <em>Sensors</em> palette, returns true
if the mouse button is clicked. The mouse button block can be used to
create some interactivity in your program.</p>
<p><img src="x_block.svg" alt="x_block.svg" title="cursorx"></p>
<p><img src="y_block.svg" alt="y_block.svg" title="cursory"></p>
<p>The <em>Cursor x</em> and <em>Cursor y</em> blocks, also found on the <em>Sensors</em> palette, return the X and Y coordinates of the cursor. These blocks can also be used to create interactive programs.</p>
<p><img src="push_block.svg" alt="push_block.svg" title="push"></p>
<p><img src="pop_block.svg" alt="pop_block.svg" title="pop"></p>
<p>The <em>Push</em> and <em>Pop</em> blocks, found on the <em>Heap</em> palette, are used to
store and retrieve values on/from a first-in, last-out (FILO) program
heap.</p>
<p><img src="print_block.svg" alt="print_block.svg" title="print"></p>
<p>The <em>Print</em> block, found on the <em>Extras</em> palette, is used to print
messages during program execution. It is very useful as a debugging
tool and also as a means of adding lyrics to your music—think
karaoke.</p>
<h2 id="widget-palette">Widget Palette</h2>
<p>Music Blocks has various Widgets that can be used within Music Blocks
to enhance your experience. The <em>Pitch-time matrix</em> is described here.</p>
<p><img src="matrix_block.svg" alt="matrix_block.svg" title="The Pitch-Time Matrix"></p>
<p>Many of the blocks on this palette are used to create a matrix of
"pitch" and "note value". The matrix is a convenient and intuitive way
for generating short musical gestures, which can be regenerated as a
"chunk of notes" that can be played back programmatically. Musicians
may find it helpful to think of the pitches within the pitch-time
matrix as being akin to a bellset in which notes may be added and
removed as desired. The "note value" representation acts as a
"rhythmic tablature" that should be readable by both those familiar
with the concepts of rhythm in music and those unfamiliar (but
familiar with math).</p>
<p><img src="../guide/matrix1.svg" alt="matrix1.svg" title="Pitch-time Matrix blocks"></p>
<p><em>Pitch-time Matrix</em> blocks clamp is used to define the matrix:
A row in the matrix is created for each <em>Pitch</em> block and columns are
created for individual notes, which are created by using <em>Rhythm</em>
blocks, individual note blocks, or the <em>Tuplet</em> block.</p>
<p><img src="../guide/matrix6.svg" alt="matrix6.svg" title="Rhythm block"></p>
<p>The <em>Rhythm</em> block is used to specify a series of notes of the same
duration (e.g., three quarter notes or seven eighth notes). The number
of notes is the top argument; the bottom argument is the the note
duration, e.g., <code>1/1</code> for a whole note, <code>1/2</code> for a half note, <code>1/4</code>
for a quarter note, etc. (Recall that in traditional Western notation
all note values are (1) in powers of two, and are (2) in relation to
the "whole note", which is in turn (3) defined by tempo, or
beats—usually quarter notes—per minute) Each note is
represented by a column in the matrix.</p>
<p>Special ratios of the whole note can be created very easily with the
<em>Rhythm</em> block by choosing an integer other than the traditional
"powers of two" that standard Western music notation affords us. For
example, putting a <code>1/5</code> into the argument for "note value" will
create a note value equal to "one fifth the durational length of a
whole note". This gives the user endless rhythmic possibilities.</p>
<p>As a convenience, blocks for the most common note values are also
provided (whole note through 64th note). They are automatically
converted into the corresponding <em>Rhythm</em> blocks, which can be used to
create columns in the matrix.</p>
<p>If you would like multiple note values in a row, simply use the
<em>Repeat</em> block clamp or <em>Duplicate</em> block clamp.</p>
<p><img src="../guide/matrix9.svg" alt="matrix9.svg" title="simple Tuplet block"></p>
<p><img src="../guide/matrix11.svg" alt="matrix11.svg" title="Tuplet clamp"></p>
<p>The <em>Tuplet</em> block is how we create rhythms that do not fit into a
simple "power of two" rhythmic space. A tuplet, mathematically, is a
collection of notes that are scaled to map into a specified
duration. For example, if you would like to script/perform three
unique notes into the duration of a single quarter note you would use
the tuplet block. The <em>Tuplet</em> block is able to calculate how many
notes you have inserted into the clamp and will generate the tuplet
accordingly (e.g. if you put three notes in, it will generate a
"triplet". We have designed the tuplet block to allow for any input of
note value, so the triplet can be three quarter notes, three eighth
notes, etc. This design choice allows for maximum flexibility) You can
mix and match <em>Rhythm</em> and individual <em>Note</em> blocks within a <em>Tuplet</em>
block to generate complex rhythms (e.g. two quarter notes plus an
eighth note is possible within the tuplet). Each note is represented
by a column in the matrix.</p>
<p>Note: Each time you open the matrix, it tries to reconstruct the notes
marked from the previous matrix. If you modify the <em>Pitch</em> and
<em>Rhythm</em> blocks in the <em>Pitch-time Matrix</em> clamp, Music Blocks will
try to make a corresponding change in the matrix.</p>
<p>Note: You can construct a matrix from a chuck of blocks by including
the chunk in the clamp of the <em>Pitch-time Marix</em> block.</p>
<p>More details about all of the widgets are available in the
<a href="http://github.com/sugarlabs/musicblocks/tree/master/guide/index.html">Music Blocks Programming Guide</a>.</p>
</div>
</div>
</body>
</html>