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
5595 lines (5587 loc) · 264 KB
/
index.html
File metadata and controls
5595 lines (5587 loc) · 264 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
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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">
<p>
<a href="../guide/index.html">English</a> |
<a href="../guide-es/index.html">Español</a> |
<a href="../guide-ja/index.html">日本語</a> |
<a href="../guide-zhCN/index.html">中文</a> |
<a href="../guide-pt/index.html">Português</a>
</p>
<h1 id="guide-to-programming-with-music-blocks">Guide to Programming with Music Blocks</h1>
<p>
Music Blocks is a programming environment for children interested in music and graphics.
It expands upon Turtle Blocks by adding a collection of features relating to pitch and
rhythm.
</p>
<p>
The
<a href="https://github.com/sugarlabs/turtleblocksjs/blob/master/guide/README.md"
>Turtle Blocks guide</a
>
is a good place to start learning about the basics. In this guide, we illustrate the
musical features by walking the reader through numerous examples.
</p>
<p>
The Music Blocks <a href="../documentation/README.md">basic documentation</a> is also a
good resource.
</p>
<p>
And there is a short <a href="../Debugging.md">Guide to Debugging</a> to help you with
your programming.
</p>
<p>This guide details the many musical features of the language.</p>
<h2 id="table-of-contents"><a name="TOC">TABLE OF CONTENTS</a></h2>
<ol type="1">
<li><a href="#1-getting-started">Getting Started</a></li>
<li>
<a href="#2-making-sounds">Making Sounds</a>
<ol type="1">
<li><a href="#21-note-value-blocks">Note Value Blocks</a></li>
<li><a href="#22-pitch-blocks">Pitch Blocks</a></li>
<li><a href="#23-multiple-pitches">Multiple pitches</a></li>
<li><a href="#24-rests">Rests</a></li>
<li><a href="#25-drums">Drums</a></li>
</ol>
</li>
<li>
<a href="#3-programming-with-music">Programming with Music</a>
<ol type="1">
<li><a href="#31-actions">Actions</a></li>
<li>
<a href="#32-pitch-transformations">Pitch Transformations</a>
<ol type="1">
<li><a href="#321-step-pitch-block">Step Pitch Block</a></li>
<li><a href="#322-sharps-and-flats">Sharps and Flats</a></li>
<li><a href="#323-adjusting-transposition">Adjusting Transposition</a></li>
<li><a href="#324-summary-of-pitch-movements">Summary of Pitch Movements</a></li>
<li><a href="#325-set-key">Set Key</a></li>
<li>
<a href="#326-fixed-and-movable-pitch-systems"
>Fixed and Movable Pitch Systems</a
>
</li>
<li>
<a href="#327-intervals">Intervals</a>
<ol type="1">
<li><a href="#3271-absolute-intervals">Absolute Intervals</a></li>
<li><a href="#3272-ratio-intervals">Ratio Intervals</a></li>
</ol>
</li>
<li><a href="#328-chords">Chords</a></li>
<li><a href="#329-inversion">Inversion</a></li>
<li><a href="#3210-converters">Converters</a></li>
</ol>
</li>
<li>
<a href="#33-note-value-transformations">Note Value Transformations</a>
<ol type="1">
<li><a href="#331-dotted-notes">Dotted Notes</a></li>
<li>
<a href="#332-speeding-up-and-slowing-down-notes-via-mathematical-operations"
>Speeding Up and Slowing Down Notes via Mathematical Operations</a
>
</li>
<li><a href="#333-repeating-notes">Repeating Notes</a></li>
<li>
<a href="#334-swinging-notes-and-tied-notes">Swinging Notes and Tied Notes</a>
</li>
<li><a href="#335-beat">Beat</a></li>
<li><a href="#336-staccato-and-slur">Staccato and Slur Blocks</a></li>
<li><a href="#337-backwards">Backwards</a></li>
</ol>
</li>
<li>
<a href="#34-other-transformations">Other Transformations</a>
<ol type="1">
<li>
<a href="#341-set-volume-and-crescendo">Set Volume and Crescendo Blocks</a>
</li>
<li><a href="#342-setting-instrument">Setting Instrument</a></li>
<li><a href="#343-setting-key-and-mode">Setting Key and Mode</a></li>
<li><a href="#344-vibrato-tremelo-et-al">Vibrato, Tremelo, et al.</a></li>
</ol>
</li>
<li><a href="#35-voices">Voices</a></li>
<li><a href="#36-adding-graphics">Graphics</a></li>
<li><a href="#37-interactions">Interactions</a></li>
<li><a href="#38-ensemble">Ensemble</a></li>
</ol>
</li>
<li>
<a href="#4-widgets">Widgets</a>
<ol type="1">
<li><a href="#41-status">Monitoring Status</a></li>
<li>
<a href="#42-generating-chunks-of-notes">Generating groups of Notes</a>
<ol type="1">
<li><a href="#421-the-phrase-maker">The Phrase Maker</a></li>
<li><a href="#422-the-rhythm-block">The Rhythm Block</a></li>
<li><a href="#423-creating-tuplets">Creating Tuplets</a></li>
<li><a href="#424-what-is-a-tuplet">What is a Tuplet?</a></li>
<li><a href="#425-using-individual-notes">Using Individual Notes</a></li>
<li><a href="#426-using-a-scale-of-pitches">Using a Scale of Pitches</a></li>
</ol>
</li>
<li>
<a href="#43-generating-rhythms"
>Generating Rhythms (or How to Make a Drum Machine)</a
>
</li>
<li><a href="#44-musical-modes">Musical Modes</a></li>
<li><a href="#45-meters">Changing Meter</a></li>
<li><a href="#46-the-pitch-drum-matrix">The Pitch-Drum Matrix</a></li>
<li><a href="#47-exploring-musical-proportions">Exploring Musical Proportions</a></li>
<li><a href="#48-generating-arbitrary-pitches">Generating Arbitrary Pitches</a></li>
<li><a href="#49-changing-tempo">Changing Tempo</a></li>
<li><a href="#410-custom-timbres">Creating Custom Timbres</a></li>
<li><a href="#411-the-music-keyboard">The Music Keyboard</a></li>
<li><a href="#412-changing-temperament">Changing Temperament</a></li>
<li><a href="#413-the-oscilloscope">The Oscilloscope</a></li>
<li><a href="#414-the-sampler">The Sampler</a></li>
<li><a href="#415-arpeggio">Arpeggio</a></li>
</ol>
</li>
<li>
<a href="#5-beyond-music-blocks">Beyond Music Blocks</a>
<ol type="1">
<li><a href="#51-lilypond">LilyPond (or How to Generate Sheet Music)</a></li>
<li><a href="#52-other-exports">Other Exports</a></li>
<li><a href="#53-the-javascript-editor">The JavaScript Editor</a></li>
</ol>
</li>
<li>
<a href="#6-appendix">Appendix</a>
<ol type="1">
<li><a href="#61-beginner-palettes">Beginner Palette Tables</a></li>
<li><a href="#62-advanced-palettes">Advanced Palette Tables</a></li>
</ol>
</li>
</ol>
<p>
Many of the examples given in the guide have links to code you can run. Look for
<code>RUN LIVE</code> links.
</p>
<h2 id="1-getting-started"><a name="#GETTING-STARTED">1. Getting Started</a></h2>
<p>
<a href="#TOC">Back to Table of Contents</a> |
<a href="#NOTES">Next Section (2. Making Sounds)</a>
</p>
<p>
Music Blocks is designed to run in a browser. Most of the development has been done in
Chrome, but it should also work in Firefox, Opera, and some versions of Safari. You can
run it from <a href="https://musicblocks.sugarlabs.org">musicblocks.sugarlabs.org</a>,
from <a href="https://musicblocks.sugarlabs.org">github io</a>, or by downloading a copy
of the code and running a local copy directly from the file system of your computer. (Note
that when running locally, you may have to use a local server to expose all of the
features.)
</p>
<p>
This guide details the music-specific features of Music Blocks. You may also be interested
in the
<a href="http://github.com/sugarlabs/turtleblocksjs/tree/master/guide"
>Turtle Blocks Guide</a
>, which reviews many programming features common to both projects.
</p>
<p>
For more details on how to use Music Blocks, see
<a href="http://github.com/sugarlabs/musicblocks/tree/master/documentation"
>Using Music Blocks</a
>. For more details on how to use Turtle Blocks, see
<a href="http://github.com/sugarlabs/turtleblocksjs/tree/master/documentation"
>Using Turtle Blocks JS</a
>.
</p>
<h2 id="2-making-sounds"><a name="NOTES">2. Making Sounds</a></h2>
<p>
<a href="#1-getting-started">Previous Section (1. Getting Started)</a> |
<a href="#TOC">Back to Table of Contents</a> |
<a href="#3-programming-with-music">Next Section (3. Programming with Music)</a>
</p>
<p>
Music Blocks incorporates many common elements of music, such as
<a href="#22-pitch-blocks">pitch</a>, <a href="#21-note-value-blocks">rhythm</a>,
<a href="#341-set-volume-and-crescendo">volume</a>, and, to some degree,
<a href="#342-setting-instrument">timbre</a> and
<a href="#344-vibrato-tremelo-et-al">texture</a>.
</p>
<h3 id="21-note-value-blocks"><a name="NOTE-VALUE">2.1 Note Value Blocks</a></h3>
<p>
At the heart of Music Blocks is the <em>Note value</em> block. The
<em>Note value</em> block is a container for a
<a href="#22-pitch-blocks"><em>Pitch</em> block</a> that specifies the duration (note
value) of the pitch.
</p>
<p>
<img
src="./note1.svg"
title="A single Note value block (top) and two consecutive Note valueblocks (bottom)"
alt="notes"
/>
</p>
<p>
At the top of the example above, a single (detached) <em>Note value</em> block is shown.
The <code>1/8</code> is value of the note, which is, in this case, an eighth note.
</p>
<p>
At the bottom, two notes that are played consecutively are shown. They are both
<code>1/8</code> notes, making the duration of the entire sequence <code>1/4</code>.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1726138873526815&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
<img
src="./note2.svg"
title="A quarter note, a sixteenth note, and a half note Note value blocks"
alt="notes"
/>
</p>
<p>
In this example, different note values are shown. From top to bottom, they are:
<code>1/4</code> for an quarter note, <code>1/16</code> for a sixteenth note, and
<code>1/2</code> for a half note.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1726139143565736&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
Note that any mathematical operations can be used as input to the <em>Note value</em>.
</p>
<p>
<img src="./piemenu1.svg" title="A pie menu for selecting note values." alt="pie menu" />
</p>
<p>As a convenience, a pie menu is used for selecting common note values.</p>
<p>
<img
src="../charts/NotationRestChart.svg"
title="A chart of note values and their corresponding note value blocks"
alt="Rest Chart"
onclick="toggleImageSize(this)"
style="max-width: 500px; max-height: 500px; cursor: pointer"
/>
</p>
<script>
function toggleImageSize(img) {
if (img.style.maxWidth === "none") {
img.style.maxWidth = "500px";
img.style.maxHeight = "500px";
} else {
img.style.maxWidth = "none";
img.style.maxHeight = "none";
}
}
</script>
<p style="color: gray;">The image dimensions exceed the optimal size. Kindly select the image to access an expanded view.</p>
<p>Please refer to the above picture for a visual representation of note values.</p>
<h3 id="22-pitch-blocks"><a name="PITCH">2.2 Pitch Blocks</a></h3>
<p>
As we have seen, <em>Pitch</em> blocks are used inside the
<a href="#21-note-value-blocks"><em>Note value</em></a> blocks. The <em>Pitch</em> block
specifies the pitch name and pitch octave of a note that in combination determines the
frequency (and therefore pitch) at which the note is played.
</p>
<p>
<img
src="./note3.svg"
title="Specifying a pitch block's name and octave"
alt="pitch block"
/>
</p>
<p>
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733100820296221&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
There are many systems you can use to specify a <em>pitch</em> block's name and octave.
Some examples are shown above.
</p>
<p>
The top <em>Pitch</em> block is specified using a <em>Solfege</em> block (<code>Sol</code>
in <code>Octave 4</code>), which contains the notes <code>Do Re Me Fa Sol La Ti </code>.
</p>
<p>
The pitch of the next block is specified using a <em>Pitch-name</em> block (<code>G</code>
in <code>Octave 4</code>), which contains the notes <code>C D E F G A B</code>.
</p>
<p>
The next block is specified using a <em>Scale-degree</em> block (the
<code>5th note</code> in the scale, 'G', also in 'Octave 4'),
<code>C == 1, D == 2, ...</code>. The <em>Scale-Degree</em> block has numbers like the
<em>Number</em> block, but also has an accidental so that the user may play pitches
outside a given key.
</p>
<p>
The next blocks is specified using a <em>Nth Modal Pitch</em> block. This block takes a
number argument and turns it into the "nth pitch of a given scale" with an index of 0
(i.e. C for C major is 0). Therefore in order to get <code>G</code>, we input the number
4. The octave argument will force the octave up or down; otherwise the user may just keep
going up or down in either direction to go through scalar pitches of any mode.
</p>
<p>
The next block is specified using a <em>Pitch-number</em> block (the
<code>7th semi-tone</code> above <code>C</code> in <code>Octave 4</code> is
<code>G</code>). The offset for the pitch number can be modified using the
<em>Set-pitch-number-offset</em> block.
</p>
<p>
The pitch of the next block is specified using the <em>Hertz</em> block in conjunction
with a <em>Number</em> block (<code>392</code> Hertz is <code>G</code> in
<code>Octave 4</code>), which corresponds to the frequency of the sound made.
</p>
<p>
The octave is specified using a number block and is restricted to whole numbers. In the
case where the pitch name is specified by frequency, the octave is ignored.The octave
argument can also be specified using a <em>Text</em> block with values <em>current</em>,
<em>previous</em>, <em>next</em> which does as 0, -1, 1 respectively.
</p>
<p>
The octave of the next block is specified using a <em>current</em> text block (<code
>Sol</code
>
in <code>Octave 4</code>).
</p>
<p>
The octave of the next block is specified using a <em>previous</em> text block (<code
>G</code
>
in <code>Octave 3</code>).
</p>
<p>
The octave of the last block is specified using a <em>next</em> text block (<code>G</code>
in <code>Octave 5</code>).
</p>
<p>Note that the pitch name can also be specified using a <em>Text</em> block.</p>
<p><img src="./piemenu2.svg" title="A pie menu for selecting pitch." alt="pie menu" /></p>
<p>As a convenience, a pie menu is used for selecting pitch, accidental, and octave.</p>
<p style="color: gray;">The image dimensions exceed the optimal size. Kindly select the image to access an expanded view.</p>
<p>
<img
src="../charts/KeyboardChart.svg"
title="Note layout chart for keyboard"
alt="Note Chart"
onclick="toggleImageSize(this)"
style="max-width: 500px; max-height: 500px; cursor: pointer"
/>
</p>
<script>
function toggleImageSize(img) {
if (img.style.maxWidth === "none") {
img.style.maxWidth = "500px";
img.style.maxHeight = "500px";
} else {
img.style.maxWidth = "none";
img.style.maxHeight = "none";
}
}
</script>
<p>
<img
src="../charts/MalletChart.svg"
title="Note layout chart for mallet"
alt="Mallet Chart"
onclick="toggleImageSize(this)"
style="max-width: 500px; max-height: 500px; cursor: pointer"
/>
</p>
<script>
function toggleImageSize(img) {
if (img.style.maxWidth === "none") {
img.style.maxWidth = "500px";
img.style.maxHeight = "500px";
} else {
img.style.maxWidth = "none";
img.style.maxHeight = "none";
}
}
</script>
<p>
Please refer to the above charts for a visual representation of where notes are located on
a keyboard or staff.
</p>
<h3 id="23-multiple-pitches"><a name="MULTI-PITCH">2.3 Multiple Pitches</a></h3>
<p>
<img
src="./note4.svg"
title="Playing multiple pitches in one note"
alt="multiple pitch"
/>
</p>
<p>
Multiple, simultaneous pitches can be specified by adding multiple <em>Pitch</em> blocks
into a single <em>Note value</em> block, like the above example.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1725793652385126&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<h3 id="24-rests"><a name="RESTS">2.4 Rests</a></h3>
<p><img src="./silence.svg" title="Silence blocks create rests" alt="silence block" /></p>
<p>
A rest of the specified note value duration can be constructed using a
<em>Silence</em> block in place of a <em>Pitch</em> block.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1725793737126028&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<h3 id="25-drums"><a name="DRUMS">2.5 Drums</a></h3>
<p><img src="./drum1.svg" title="Using Drum Sample block" alt="drum" /></p>
<p>
Anywhere a <em>Pitch</em> block can be used—e.g., inside of the matrix or a
<em>Note value</em> block—a <em>Drum Sample</em> block can also be used instead. Currently
there about two dozen different samples from which to choose. The default drum is a kick
drum.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1725793852737369&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
<img src="./note5.svg" title="Multiple Drum Sample blocks in combinations" alt="drums" />
</p>
<p>
Just as in the <a href="#23-multiple-pitches">multi-pitch</a> example above, you can use
multiple <em>Drum</em> blocks within a single <em>Note value</em> blocks, and combine them
with <em>Pitch</em> blocks as well.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1725793935277059&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<h2 id="3-programming-with-music">
<a name="PROGRAMMING-WITH-MUSIC">3. Programming with Music</a>
</h2>
<p>
<a href="#2-making-sounds">Previous Section (2. Making Sounds)</a> |
<a href="#TOC">Back to Table of Contents</a> |
<a href="#4-widgets">Next Section (4. Widgets)</a>
</p>
<p>
This section of the guide discusses how to use chunks of notes to program music. Note that
you can program with chunks you create by hand or use
<a href="#42-generating-chunks-of-notes"><em>The Phrase Maker</em></a> widget to help you
get started.
</p>
<h3 id="31-actions"><a name="ACTIONS">3.1 Actions</a></h3>
<p><img src="./chunk-2.svg" title="working of action stack" alt="action" /></p>
<p><img src="./chunk-1.svg" title="using action inside Start block" alt="action" /></p>
<p>
<a href="https://musicblocks.sugarlabs.org/index.html?id=1725788353457649&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
Every time you create a new <em>Action</em> stack, Music Blocks creates a new block
specific to, and linked with, that stack. (The new block is found at the top of the
<em>Block</em> palette, found on the left edge of the screen.) Clicking on and running
this block is the same as clicking on your stack. By default, the new blocks are named
<code>chunk</code>, <code>chunk1</code>, <code>chunk2</code>... but you can rename them by
editing the labels on the <em>Action</em> blocks.
</p>
<p>
An <em>Action</em> block contains a sequence of actions that will only be executed when
the block is referred to by something else, such as a start block. This is useful in
orchestrating more complex programs of music.
</p>
<p>
A <em>Start</em> Block is an <em>Action</em> that will automatically be executed once the
start button is pressed. This is where most of your programs will begin at. There are many
ways to <em>Run</em> a program: you can click on the <em>Run</em> button at the upper-left
corner of the screen to run the music at a fast speed; a long press on the
<em>Run</em> button will run it slower (useful for debugging); and the
<em>Step</em> button can be used to step through the program one block per button press.
(An extra-long press of the <em>Run</em> button will play back the music slowly. A long
press of the <em>Step</em> button will step through the program note by note.)
</p>
<p>
In the example above, the <em>Action</em> block named "chunk" is inside of a
<em>Start</em> block, which means that when any of the start buttons is pressed, the code
inside the <em>Start</em> block (the <em>Action</em> block) will be executed. You can add
more chunks after this one inside the <em>Start</em> block to execute them sequentially.
</p>
<p><img src="./chunk-3.svg" title="usage of multiple`c action blocks" alt="action" /></p>
<p><img src="./chunk-4.svg" title="usage of Repeat block" alt="repeat action" /></p>
<p>
You can <a href="#333-repeating-notes">repeat</a> actions either by using multiple
<em>Action</em> blocks or using a <em>Repeat</em> block.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1725788849659637&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p><img src="./chunk-6.svg" title="multiple action stacks" alt="multiple actions" /></p>
<p><img src="./chunk-5.svg" title="mixing and matching chunks" alt="mixing actions" /></p>
<p>
You can also mix and match actions. Here we play the <em>Action</em> block with name
<code>chunk0</code>, followed by <code>chunk1</code> twice, and then
<code>chunk0</code> again.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1725789807251793&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p><img src="./chunk-8.svg" title="creating a song using actions" alt="actions" /></p>
<p><img src="./chunk-7.svg" title="usage of Repeat block in a song" alt="repeat" /></p>
<p>
A few more chunks and we can make a song. (Can you read the block notation well enough to
guess the outcome? Are you familiar with the song we created?)
<a href="https://musicblocks.sugarlabs.org/index.html?id=1725791527821787&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<h3 id="32-pitch-transformations">
<a name="PITCH-TRANSFORMATION">3.2 Pitch Transformations</a>
</h3>
<p>There are many ways to transform pitch, rhythm, and other sonic qualities.</p>
<h4 id="321-step-pitch-block"><a name="STEP-PITCH">3.2.1 Step Pitch Block</a></h4>
<p><img src="./transform0.svg" title="Using the Step Pitch block" alt="step pitch" /></p>
<p>
The <em>Step Pitch</em> block will move up or down notes in a scale from the last played
note. In the example above, <em>Step Pitch</em> blocks are used inside of
<em>Repeat</em> blocks to repeat the code <code>7</code> times, playing up and down a
scale.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1732586286359989&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
<img
src="./transform16.svg"
title="Using the Scalar Step Up and Down blocks"
alt="scalar step"
/>
</p>
<p>
Another way to move up and down notes in a scale is to use the <em>Scalar Step Up</em> and
<em>Scalar Step Down</em> blocks. These blocks calculate the number of half-steps to the
next note in the current mode. (You can read more about
<a href="#44-musical-modes">Musical Modes</a> below.) Note that the
<em>Mouse Pitch Number</em> block returns the pitch number of the most recent note played.
</p>
<p>
In this example, we are using the <em>Mode length</em> block, which returns the number of
scalar steps in the current mode (7 for Major and Minor modes).
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733192676935416&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<h4 id="322-sharps-and-flats"><a name="SHARPS-AND-FLATS">3.2.2 Sharps And Flats</a></h4>
<p>
<img src="./transform1.svg" title="Using Sharp and Flat blocks" alt="sharp and flat" />
</p>
<p>
The <em>Accidental</em> block can be wrapped around <em>Pitch</em> blocks,
<em>Note value</em> blocks, or chunks of notes inside of
<a href="#31-actions"><em>Action</em></a> blocks. A sharp will raise the pitch by one half
step. A flat will lower by one half step. In the example, on the left, just the
<em>Pitch</em> block <code>re</code> is lowered by one half step; on the right, both
<em>Pitch</em> blocks are raised by one half step. (You can also use a double-sharp or
double-flat accidental.)
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733231694757697&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<h4 id="323-adjusting-transposition">
<a name="ADJUST-TRANSPOSITION">3.2.3 Adjusting Transposition</a>
</h4>
<p><img src="./transform2.svg" title="Adjusting transpositions" alt="transposition" /></p>
<p>
There are multiple ways to transpose a pitch: by semi-tone or scalar steps or by a ratio.
The <em>Semi-tone-transposition</em> block (above left) can be used to make larger shifts
in pitch in half-step units. A positive number shifts the pitch up and a negative number
shifts the pitch down. The input must be a whole number. To shift up an entire octave,
transpose by <code>12</code> half-steps. <code>-12</code> will shift down an entire
octave.
</p>
<p>
The <em>Scalar-transposition</em> block (above right) shifts a pitch based on the current
key and mode. For example, in <code>C Major</code>, a scalar transposition of
<code>1</code> would transpose <code>C</code> to <code>D</code> (even though it is a
transposition of <code>2</code> half steps). To transpose <code>E</code> to
<code>F</code> is <code>1</code> scalar step (or <code>1</code> half step). To shift an
entire octave, scalar transpose by the mode length up or down. (In major scales, the mode
length is <code>7</code>.)
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733306280056376&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
<img
src="../documentation/setratio_block.svg"
title="raising by a fifth using transpose by ratio"
alt="ratio transposition"
/>
</p>
<p>
The <em>Transpose-by-ratio</em> block shifts a pitch based on a ratio. For example, a
ratio of 2:1 would shift a pitch by an octave; a ratio of 3:2 would shift a pitch by a
fifth.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733307313746261&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
As a convenience, a number of standard scalar transpositions are provided:
<em>Unison</em>, <em>Second</em>, <em>Third</em>, ..., <em>Seventh</em>,
<em>Down third</em>, and <em>Down sixth</em>, as well as a transposition for
<em>Octave</em>.
</p>
<p>
<img
src="./transform3.svg"
title="raising an octave using semi-tone-transposition"
alt="semi-tone transposition"
/>
</p>
<p>
In the example above, we take the song we programmed previously and raise it by one
octave.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733340896349788&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
<img src="./50cent_block.svg" title="adding 50 cents to a pitch using the semitone-transposition" alt="Semi-tone transpose Block with cents" />
</p>
<p>
A cent is a unit of measure for the ratio between two frequencies. A semitone is defined as 100 cents. The frequency between two adjacent pitches would be 50 cents. You can use the <em>Semitone transpose</em> block to shift a pitch by cents.
</p>
<p>
In the example above, G4 + 50 cents is 403Hz. (Recall that G4 is 392Hz and G#4 is 415Hz).
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733411391096443&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p>
<img src="./50cents_by_ratio.svg" title="adding 50 cents to a pitch
using the ratio block" alt="cents by ratio" />
</p>
<p>
You can also use the ratio block for cents, although the math is a bit more complicated.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733425512725578&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<p><img src="./transform18.svg" title="The Register block" alt="register" /></p>
<p>
The <em>Register</em> block provides an easy way to modify the register (octave) of the
notes that follow it. In the example above it is first used to bump the
<code>Mi 4</code> note up by one octave and then to bump the <code>Sol 4</code> note down
by one octave.
<a href="https://musicblocks.sugarlabs.org/index.html?id=1733426232664999&run=True" target="_blank"
>RUN LIVE</a
>
</p>
<h4 id="324-summary-of-pitch-movements">
<a name="PITCH-MOVEMENT">3.2.4 Summary of Pitch Movements</a>
</h4>
<table>
<thead>
<tr class="header">
<th>Representation</th>
<th>Pitch Movement</th>
<th>Properties</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Scalar Step</td>
<td>scalar</td>
<td>0=no change</td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td>1=next scalar pitch in current key and mode</td>
</tr>
<tr class="odd">
<td></td>
<td></td>
<td>-1=previous scalar pitch in current key and mode</td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td>
If the argument to scalar step is positive, it moves up the scale; if it is
negative, it moves down the scale.
</td>
</tr>
</tbody>
</table>
<table>
<thead>
<tr class="header">
<th>Music Blocks Code for Scalar Step</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><img src="./pitchmovement1.svg" title="scalar" alt="scalar" /></td>
</tr>
<tr class="even">
<td>
The example above demonstrates traveling up and down the major scale by moving an
octave up from the starting note, do, one note at a time and then back down the same
way.
</td>
</tr>
</tbody>
</table>
<table>
<thead>
<tr class="header">
<th>Standard Notation with Scalar Step</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>
<img
src="./pitchmovement1.png"
title="scalar step up and down"
alt="scalar step up and down"
/>
</td>
</tr>
</tbody>
</table>
<table>
<thead>
<tr class="header">
<th>Representation</th>
<th>Pitch Movement</th>
<th>Properties</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Transposition</td>
<td>Semi-tone</td>
<td>Creates shifts in pitch by half-steps</td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td>
If the argument to transpose is positive, it will shift upwards in pitch; if it is
negative, there will be a downwards shift.
</td>
</tr>
<tr class="odd">
<td></td>
<td></td>
<td>There are 12 half-steps shifts per octave.</td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td>An argument of -12 will shift down one octave.</td>
</tr>
<tr class="odd">
<td></td>
<td></td>
<td>An argument of zero will not change the pitch.</td>
</tr>
</tbody>
</table>
<table>
<thead>
<tr class="header">
<th>Music Blocks Code with Scalar Transpose</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>
<img
src="./pitchmovement2.svg"
title="semi-tone transposition"
alt="semi-tone transposition"
/>
</td>
</tr>
</tbody>
</table>
<table>
<thead>
<tr class="header">
<th>Standard Notation for Scalar Transpose</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>
<img
src="./pitchmovement2.png"
title="semi-tone transposition"
alt="semi-tone transposition"
/>
</td>
</tr>
</tbody>
</table>
<table>
<thead>
<tr class="header">
<th>Representation</th>
<th>Pitch Movement</th>
<th>Properties</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Transposition</td>
<td>Scalar</td>
<td>Shifts the pitch based on the current key and mode</td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td>Each number represents a scalar step.</td>
</tr>
<tr class="odd">
<td></td>
<td></td>
<td>
Scalar transposition can transform your original key to a new key by counting the
notes between the keys.
</td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td>For example: Transposing C-D-E-F by 4 (fifth) will give us G-A-B-C</td>
</tr>
<tr class="odd">
<td></td>
<td></td>
<td>
To transpose an octave: shift by the mode length (7 in major scales) up or down.
</td>
</tr>
</tbody>
</table>
<h4 id="325-set-key"><a name="SET-KEY">3.2.5 Set Key</a></h4>
<p>
The <em>Set key</em> block is used to change both the mode and key of the current scale.
(The current scale is used to define the mapping of Solfege [when set Movable Do = True]
to notes and also the number of half steps take by the the <em>Scalar step</em> block.)
For example, by setting the key to C Major, the scale is defined by starting at C (or Do)
and applying the pattern of half steps defined by a Major mode. In this case, the pattern
of steps skips past all of the sharps and flats. (On a piano, C Major is just the white
keys).
</p>
<p>
When using the <em>Set key</em> block, the mode argument is used to define the pattern of
half steps and the key argument is used to define the starting position of the pattern.
For example, when mode = "major" and key = "C", the pattern of half steps is 2 2 1 2 2 2 1
and the first note in the scale from which the pattern is applied is "C".
</p>
<table>
<thead>
<tr class="header">
<th>Set Key Example</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><img src="./setkey1.svg" title="set key example" alt="set key" /></td>
</tr>
</tbody>
</table>
<p>
Using the example above, one can modify the arguments to <em>Set key</em> in order to move
up and down one octave in a scale. The example shows G Major scale, which has an F#, but
it could be used for any combination of key and mode.
</p>
<table>
<thead>
<tr class="header">
<th>Standard Notation for Set Key Example</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>
<img src="./setkey2.png" title="Standard Notation Set Key" alt="set key notation" />
</td>
</tr>
</tbody>
</table>
<p>
<a href="https://musicblocks.sugarlabs.org/index.html?id=1662103714150464&run=True"
>RUN LIVE</a
>
</p>
<p>Various examples for Major modes are shown in the following table.</p>
<table>
<thead>
<tr class="header">
<th>Key</th>
<th>Mode</th>
<th>Mode Pattern in Half Steps</th>
<th>Pitch Pattern</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>C</td>
<td>Major</td>
<td>2 2 1 2 2 2 1</td>
<td>C, D, E, F, G, A, B, C</td>
</tr>
<tr class="even">
<td>G</td>
<td>Major</td>
<td>2 2 1 2 2 2 1</td>
<td>G, A, B, C, D, E, F#, G</td>
</tr>
<tr class="odd">
<td>D</td>
<td>Major</td>
<td>2 2 1 2 2 2 1</td>
<td>D, E, F#, G, A, B, C#, D</td>
</tr>
<tr class="even">
<td>F</td>
<td>Major</td>
<td>2 2 1 2 2 2 1</td>
<td>F, G, A, B♭, C, D, E, F</td>
</tr>
<tr class="odd">
<td>B♭</td>
<td>Major</td>
<td>2 2 1 2 2 2 1</td>
<td>B♭, C, D, E♭, F, G, A, B♭</td>
</tr>
</tbody>
</table>
<p>
The next table is the same sets of various keys (starting pitches), but the mode is set to
"Dorian" instead of Major.
</p>
<table>
<thead>
<tr class="header">
<th>Key</th>
<th>Mode</th>
<th>Mode Pattern in Half Steps</th>
<th>Pitch Pattern</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>C</td>