MidicaPL Tutorial, Chapter 2: Improving

This is the second chapter of the MidicaPL tutorial. Please read chapter 1 first, if you have not yet done that already.

In this chapter you will learn all the details about channel options and how to create karaoke songs. Moreover you will learn everything about complex note lengths, how to use percussion instruments, and how to use soundfonts.

Channel Options

As mentioned before, a channel command can have options. Everything after the length column is regarded as options. An option has a name and (most of the time) also a value, separated by = and/or whitespaces. If a channel command has more than one option, the options are separated by ,. Additional whitespaces are allowed, but not needed.

Each option has a long name and an abbreviation, which can be used instead of the long name. But enough theory, the Channel Options table shows the options:

Channel Options
Long Name Short Name Type Min Value Max Value
velocity v integer 1 127
duration d float >0.0 (>0%)
quantity q integer 1
multiple m none - -
lyrics l text - -
tremolo tr length - -
shift s integer -127 127

Velocity

The velocity is the force with which a note is played. The more velocity, the louder the note. The option name is velocity. The short form is v.

The value can be between 1 and 127. The default is 100. If the velocity option is used in a channel command, the following commands in the same channel will also use this velocity value. As long as the option is used in the same channel again, with a different value.

MidicaPL
0 c  /8				// 100 f   (default)
0 d  /8	velocity=15	// 15  ppp
0 e  /8				// 15
0 f  /8				// 15
0 g  /8	v=30		// 30  pp
0 a  /8				// 30
0 b  /8	v=50		// 50  p
0 c+ /8	v = 50		// 50
0 b  /8				// 50
0 a  /8	velocity 70	// 70  mp
0 g  /8	v=80		// 80  mf
0 f  /8	v 95		// 95  f
0 e  /8	v 110		// 110 ff
0 d  /8	v=120		// 120 fff
0 c  /8	v=127		// 127 fff (maximum)
Result (Score)

The example shows different ways to use the long or short form of the option.

Duration

The duration option describes after which percentage of the note length, the pressed key is released. The option name is duration. The short form is d. The values can be either floating point numbers or percentage values ending with %. Low values result in "staccato", high values result in "legato".

If two notes are played after each other, and the duration value is 1.0 (or 100%) then the first note is released in the same moment when the second one is pressed. A value of 0.9 (or 90%) means that the first note is released after 90% of its official duration. So the note is 10% shorter than its theoretical length.

The default value is 0.95 (or 95%), meaning that the key is released 5% before its theoretical end. Values greater than 1.0 are also allowed. Then the notes overlap: The former note is released after the following one begins.

If the duration option is used in a channel command, the following commands in the same channel will use the same duration value.

MidicaPL
0 c  /4               // 95% (default)
0 d  /4 duration=0.5  // 50%
0 e  /4               // 50%
0 f  /4 d=0.5         // 50%
0 g  /4 d=50%         // 50%
0 a  /4               // 50%
0 b  /4 d=20%         // 20%
0 c+ /4 d 0.2         // 20%
0 b  /4 d=.2          // 20%
0 a  /4               // 20%
0 g  /4 d=150%        // 150%
0 f  /4 d=1.5         // 150%
0 e  /4               // 150%
0 d  /4 d=50%, v=120  // 50%, loud
0 c  /4 v=120,d=50%   // 50%, loud
Result (Score)

This example shows different ways how to use the long or short form of the duration option, with a floating point or percentage value. The last two lines show how different options can be combined. In this case duration and velocity.

Quantity

With the quantity option you can repeat the same channel command any number of times. The option name is quantity. The short form is q.

The following example shows the beginning of "The Four Seasons: Summer", 3rd movement, by "Antonio Vivaldi".

MidicaPL
0  g    /16
0  g-   /16  quantity=11
0  f    /16
0  g-   /16  q=11

1  g-2  /8   q=6, d=50%
1  -    /8
1  g-2  /8   q=5
Result (Score)

As you can see, this option can reduce the source code lines. In channel 1 it is used for 8th notes, together with a duration value of 50%. This is an alternative to combining 16th notes with 16th rests.

Multiple

The multiple option is used to play different voices in the same channel. It allows to play different notes with different lengths and/or different velocity or duration options in the same time and channel. The option name is multiple. The short form is m. It does not have any value.

As we already know, each channel command appends a note (or a chord or a rest) to the end of a channel. To be more precise, it adds the note to a marker that is usually at the end of the channel. After adding the note, this marker is moved from the old end of the channel to the new end of the channel.

But if the channel command has the multiple option, the marker is not moved. So the next note that is added to the channel, begins at the same time like the note with the multiple option.

MidicaPL
0 c  /1  multiple
0 g  /4
0 a  /4
0 b  /4
0 c+ /4

0 c+ /1  m
0 -  /4
0 c  /4
0 e  /4
0 -  /4

0 c  /1  m
0 -  /4
0 a  /2. m
0 -  /4
0 e+ /2
Result (Score)

This example shows some possibilities to use the multiple option. The first bar uses 2 voices, shown as blue and black. The full note and the first quarter note (g) begin in the same time because of the multiple option.

In the second example we have 2 voices again (blue and black). But they don't begin in the same time, so we need to add a rest in the black voice. The blue voice sounds longer than the black one, so we need another rest at the end of the second bar.

In the third bar we have three voices: blue, green and black. They all begin at different times but end in the same time.

Lyrics

The lyrics option can be used to add a syllable to the command. This way you can make your song ready for karaoke. The option name is lyrics. The short form is l.

If you need whitespaces inside of the syllabe, you must use the following symbols:

  • _ for a space
  • \r for a new line
  • \n for a new paragraph
  • \c for a comma ,

The following example shows how to create a karaoke version of "Happy Birthday".

MidicaPL
0  c  /8.  lyrics=Hap
0  c  /16  l=py_
0  d  /4   l=birth
0  c  /4   l=day_
0  f  /4   l=to_
0  e  /2   l=you\c\r

0  c  /8.  l=hap
0  c  /16  l=py_
0  d  /4   l=birth
0  c  /4   l=day_
0  g  /4   l=to_
0  f  /2   l=you.\n

0  c  /8.  l=Hap
0  c  /16  l=py...
Result (Score)
Result (Screenshot)

The last screenshot shows how the result looks inside of the player in karaoke mode.

Tremolo

The tremolo option is an alternative notation for note (or chord) repetitions. The option name is tremolo. The short form is tr.

The note length column of a tremolo'ed note defines the overall length over all repetitions. The length of each repeated note is provided as the option value.

The next two examples are equivalent. The first one uses the tremolo option, while the second one uses the quantity option.

MidicaPL
0  c    /1  tremolo=/8

1  c,e  /1  tr /16

2  c    /4  tr=/8
2  c    /8  tr=/16
2  c    /8  tr=/32

p  bd1  /1  tr=/32
MidicaPL
0  c    /8   q=8

1  c,e  /16  q=16

2  c    /8   q=2
2  c    /16  q=2
2  c    /32  q=4

p  bd1  /32  q=32
Result (Score)

As you can see in the last line, the tremolo option can also be used to express drum rolls.

Shift

This section describes a lowlevel form of transposing. Probably you will never need it. You can find a more usable form for transpositions in the chapters 3 and 4.

The shift option transposes the given note or chord an arbitrary number of half tone steps into one direction. The option name is shift. The short form is s.

The value is the number of half tone steps for the transposition. It can be negative for a lower transposition or positive for a higher transposition.

The next two examples are equivalent. The first one uses the shift option, while the second one just uses normal notes.

MidicaPL
CHORD cmaj c+,e+,g+
0  c    /4
0  c    /4  shift=4
0  c    /4  s=-1
0  c,d# /4  s=4
0  cmaj /4  s = -12
MidicaPL
CHORD cmaj c,e,g
0  c     /4
0  e     /4
0  b-    /4
0  e,g   /4
0  cmaj  /4
Result (Score)

Length Definitions

As you learned in chapter 1, the third column of a channel command defines the length of the note (or chord or rest). The easyest form of such a length definition is an atomic length like /4. This can be modified by special symbols like .. Most of the time you don't need anything more. But in some cases you may need more complicated definitions. In those cases you can combine more than one length definition and build a sum of them.

Atomic Lengths

The following atomic lengths are defined:

/1 (full), /2 (half), /4 (quarter), /8 (eighth), /16 (sixteenth), /32 (thirty-second)

*1 (full), *2 (double), *4 (four wholes), *8 (eight wholes), *16 (sixteen wholes), *32 (thirty-two wholes)

You can also use just numbers without / or *. In this case, the number is interpreted as Xth note. This way you can also have more notes than the ones described above. E.g. 64 is interpreted as a sixty-fourth note (1/64). Or 5 will be a fifth note (1/5).

The reason, this tutorial uses /4 instead of 4 most of the time is that it's just more readable. But the result is the same.

MidicaPL
0 c  *2

1 c+ /2
1 c+ /4
1 c+ /4
1 c+  4
1 c+ /8
1 c+  8
1 -  /8
1 c+ /16
1 c+  16
1 -  /16
1 c+ /32
1 c+  32
1 -  /32
1 c+  64
1 c+  64
Result (Score)

Modified Lengths

Dot Modifiers

An atomic length can be modified. You already know the modifier .. It makes the atomic length one half longer, so that it's 3/2 of the atomic length. You can add as many dots as you want. Two dots (..) make it longer by three quarters, resulting in 7/4 of it's atomic length. Three dots result in 15/8 of the atomic length. And so on.

MidicaPL
0 c+ /2.
0 c+ /4
0 c+ /2..
0 c+ /8
0 c+ /2...
0 c+ /16

1 c  /4 q=12
Result (Score)

Channel 1 is only added for comparison reasons.

Triplet Modifiers

This section describes a lowlevel form of defining triplets. An easier to write (highlevel) form will follow in chapter 4.

A triplet modifier shortens the atomic length by one third, resulting in 2/3 of the atomic length. The triplet modifier is a t. Just like a dot, a triplet can be applied as often as you want, resulting in nested triplets. Two triplet modifiers result in a length of 4/9 (2/3 * 2/3). Three such symbols result in 8/27 (2/3 * 2/3 * 2/3). And so on.

MidicaPL
1 c- /4   q=8

0 c /8t   q=3

0 c /8t
0 c /8t.
0 c /16t

0 c /8.t
0 - /16t
0 c /8t

0 c /8t
0 c /16tt q=3
0 c /8t

0 c   /2t
0 c,e /2t
0 c   /2t
Result (Score)

Channel 1 is added for comparison reasons again. The first triplet consists of 3 shortened eighths taking the time of a quarter. The second triplet is only slightly more complicated. It also contains a dotted eighth and a sixteenth.

The third triplet contains a dotted note again. But this time the dot is placed before the t symbol. This demonstrates that the order of modifiers does not matter. The triplet also contains a rest that needs to have a modified length as well.

The fourth triplet contains a nested triplet, marked in blue. So the notes of the inner triplet need to be modified by two t symbols.

The last triplet consists of three half notes having the length of one full note. It also contains a chord.

Tuplet Modifiers

This section describes a lowlevel form of defining tuplets. An easier to write (highlevel) form will follow in chapter 4.

A triplet is only one special type of tuplet. Generally a tuplet is used to change the length of a sequence of notes in a way that has to be defined in the tuplet definition. A Tuplet modifier is defined by the symbol t, followed by two numbers that are separated by :. So a triplet could also be defined as t3:2 meaning something like "3 for 2" or "3 notes have the length of 2".

Mathematically you can say: tX:Y means that the length is multiplied with Y/X. So a note inside of a quadruplet would be modified with t4:3. And something inside a quintuplet with t5:4.

MidicaPL
1 c-  /4        q=8

0 c   /8t5:2    q=3
0 -   /8t5:2
0 c  /16t5:2    q=2

0 c   /4

0 c   /4t3:4
0 c  /16t3:4t3:2 q=3

0 c   /1t7:4
0 c,g /2t7:4
0 c   /4t7:4
Result (Score)

Again, channel 1 is only added for comparison reasons. The first tuplet is a 5:2 tuplet that could contain 5 notes (or rests) with the length of 2. So the length of each note or rest is modified by 2/5.

The second tuplet is a 3:4 tuplet modifying all lengths by 4/3. So you see that a tuplet can also be defined to make notes longer instead of shorter. This tuplet contains a nested triplet (marked in blue) that has been explicitly defined as t3:2 instead of t. Because of the nesting, both tuplet modifiers have to be attached to each other.

The last tuplet contains different note lengths and a chord.

Sums of Lengths

Sometimes a note length cannot be described easily with an atomic or modified length. But it can easily be described as a sum of two lengths. In sheet music such notes are typically printed as 2 notes with a tie between them. In MidicaPL such a note length can be described as two atomic or modified lenghts, separated by a + symbol.

The following example shows the first few notes of "Hey Jude" by the "Beatles".

MidicaPL
0 c+     /4     // Hey
*
0  a     /2+/8  // Jude
0  a     /8     // don't
0  c+    /8     // make
0  d+    /8     // it

1  f-,a- /8
1  c-    /8
1  f-,a- /8
1  c-    /8
1  f-,a- /8
1  c-    /8
1  f-,a- /8
1  c-    /8
Result (Score)

A half and an eighth note are tied together. This is described as /2+/4.

More complicated expressions are also possible like /2.+/1+/2t:

MidicaPL
0 c /4
0 c /2.+/1+/2t
0 c /2t    q=2
Result (Score)

Percussion Instruments

In order to produce sounds, we learned how to configure a certain instrument for a channel. Then we used notes to play different pitches in that channel. With Percussion instruments this is different. A percussion instrument has only one pitch. It's somthing like a drum, a hand clap, a cow bell or a triangle. Using notes for such instruments is not very useful.

Percussion instruments are usually played in channel 9, the special percussion channel. In the INSTRUMENTS block this channel cannot be associated with an instrument but with a drumkit.

When playing something later in this channel, this is not a note but a certain percussion instrument. Instead of the note name you write a percussion ID. Each percussion instrument has a long ID and a short ID. The valid IDs can be seen in the info window under Configuration / Percussion IDs.

The next two examples are equivalent. They play the intro for "We Will Rock You" by "Queen".

MidicaPL
p snare_drum_1 /8  q=2
p hand_clap    /4
p snare_drum_1 /8  q=2
p hand_clap    /4
MidicaPL
p sd1 /8  q=2
p hc  /4
p sd1 /8  q=2
p hc  /4
Result (Score)

The only difference is that the first example uses long percussion IDs and the second one uses short IDs.

Like a chord of notes, you can also play two percussion sounds in the same time. Just separate the IDs with a ,. The following example shows the beginning of "Billie Jean" by "Michael Jackson".

MidicaPL
p  hhc,bd1  /8
p  hhc      /8
p  hhc,sd1  /8
p  hhc      /8
p  hhc,bd1  /8
p  hhc      /8
p  hhc,sd1  /8
p  hhc      /8
Result (Score)
Result (Score)

The short percussion IDs from this example are equivalent to the following long IDs:

  • hhc equals hi_hat_closed
  • sd1 equals snare_drum_1
  • bd1 equals bass_drum_1

The first result score is easier to read for non-drummers. The second one is more compact and more what a drummer is used to read.

Using Soundfonts

Include Soundfont File

In the preparation section you learned how to load a Soundfont manually in the main window of the Midica application.

But there are a lot of different soundfonts out there, specialized for different kinds of music. So maybe you want to use different soundfonts for different songs. And maybe you don't want to choose the soundfont file manually each time you switch to another MidicaPL file containing another song.

In this case you can use the SOUNDFONT command. Its only argument is the path to a soundfont file in the .sf2 format. The path can be either absolute or relative to the source file containing the command.

MidicaPL
SOUNDFONT ../soundfonts/my-soundfont.sf2

Of cause this does not work on someone else's computer because he will probably not have the same soundfont in the same file path inside of his fils system. And it will also not work in an exported MIDI file because soundfont information cannot be stored in a MIDI sequence.

Bank Descriptions

In chapter 1 you already learned the simplest form of defining instruments for each channel. Remember: In the second column of each line we used an instrument ID or a drumkit ID or a MIDI program number.

Each ID is mapped to a program number internally. And program numbers can only have values from 0 to 127. But comprehensive soundfonts can contain much more than 128 different instruments. In this case the instruments are selected by a combination of a program number and a bank description.

In the second column of an instrument line the bank description can be attached to the ID or program number separated by a , symbol. So VIOLIN,5 or 40,5 would select a violin with the bank description "5".

A Bank description can consist of an MSB (0-127) and an LSB (0-127), separated by a / symbol. E.g. VIOLIN,5/3 would use a violin (program number 40) with a bank MSB of 5 and an LSB of 3.

For most soundfonts you only need the MSB, like in the first example. In this case the LSB is 0. So VIOLIN,5 is the same as VIOLIN,5/0.

And if MSB and LSB are both zero, you can omit both and only use the ID or program number. That was the case in the examples from chapter 1. So the following instrument definitions are all equal:

  • VIOLIN
  • VIOLIN,0
  • VIOLIN,0/0
  • 40
  • 40,0
  • 40,0/0

Alternatively a bank description can also be a full bank number. This can be calculated the following way:

Bank Number = MSB * 128 + LSB

That means that the following instrument definitions are equal:

  • VIOLIN,5/3
  • VIOLIN,643 (5 * 128 + 3 = 643)

Some soundfonts support multi-channel drumkits. That is a drumkit that can also be used in channels other than 9. Often such drumkits are located on bank 15360 (MSB 120, LSB 0). The following example assumes that you use such a soundfont.

MidicaPL
INSTRUMENTS
    0   2                         E-Piano on bank 0
    1   ELECTRIC_GRAND_PIANO,0    E-Piano on bank 0
    2   ELECTRIC_GRAND_PIANO,0/0  E-Piano on bank 0
    3   2,0/0                     E-Piano on bank 0
    4   40                        Fiddle
    5   ACOUSTIC_BASS             Bass
    p   ELECTRONIC                E-Drums on bank 0
    10  ELECTRONIC,120            E-Drums on bank 15360
    11  ELECTRONIC,120/0          E-Drums on bank 15360
    12  ELECTRONIC,15360          E-Drums on bank 15360
    13  24,120                    E-Drums on bank 15360
    14  24,120/0                  E-Drums on bank 15360
    15  24,15360                  E-Drums on bank 15360
END
Result (Screenshot)
Channels in the Player (Screenshot)

Instrument Switch

Sometimes you may need to switch the instrument of one or more channels. Then you have to reconfigure these channels accordingly. This can be done in a block or a single line.

Instruments Block

One way to switch instruments is to use the same kind of INSTRUMENTS block that you already know. However this block can only contain channels that you have already initialized inside of the very first INSTRUMENTS block of your source code.

If your first INSTRUMENTS block was the one from the Bank Descriptions section above, you can later define a second INSTRUMENTS block that redefines all channels except 6, 7 and 8.

Or you can redefine only channel 0, 5, 9 and 15. Then the channels 1-4 and 10-14 would continue using their already defined instruments. This would look like the following example:

MidicaPL
INSTRUMENTS
    0   41,0/0         Viola (Standard)
    5   HARPSICHORD,8  Cembalo
    p   ROOM           Room Drumset
    15  CELLO          Violoncello
END
Result (Screenshot)
Channels in the Player (Screenshot)

Single Instrument Switch

Alternatively you can reconfigure a channel in one single line. Therefore the INSTRUMENT command is used. (Pay attention to the singular form.)

The INSTRUMENT command is followed by the channel number, the instrument definition and the channel description.

The rules for channel number, instrument definition and channel details are the same as the rules inside of an INSTRUMENTS block. The only difference is that the channel description is optional. If it's ommitted, Midica re-uses the old channel description.

The following example switches the instruments of the channels 0 and 1:

MidicaPL
INSTRUMENT  0  PIZZICATO_STRINGS
INSTRUMENT  1  STEEL_GUITAR,16/0  Mandolin
Result (Screenshot)

With the first command, we simulate a switch of the viola from arco to pizzicato mode. Therefore we need a new MIDI instrument in channel 0 but not necessarily a new channel description. So we skip that.

In channel 1 we switch to a completely different instrument, using a non-standard bank number. The program number is the one of a steel guitar but in the current soundfont it's mapped to a mandolin. So we use an appropriate channel description to avoid confusion.

Another reason to use the single line instrument switch is that it also works inside of a function or block. In the next two chapters you will learn what that is.

Variables

Like in other languages you can use variables in MidicaPL. Variable names begin with a $ symbol. The rest of the variable name can consist of letters, numbers or underscores. Variable names are case-sensitive.

A variable is defined and initialized with the keyword VAR, followed by the variable name, an optional = symbol (and/or whitespaces) and the value.

Later it can be used by just writing the variable's name. The following examples are equivalent. The first one uses variables, the second one doesn't.

MidicaPL
VAR $ch  =  0
VAR $vel   80
VAR $len = /4
$ch  c  $len  v=$vel
$ch  e  $len
$ch  g  $len
VAR $ch  = 1
VAR $len = /1
VAR $n   = c+
$ch  $n,e,g  $len  v=$vel
MidicaPL
0  c       /4  v=$vel
0  e       /4
0  g       /4
1  c+,e,g  /1  v=$vel
Result (Score)

As you can see, you can assign a new value to an already defined variable. This works exactly like the initial definition.

Limitations of Variables

There are some limitations for the usage of variables.

  • A variable cannot contain any whitespaces.
  • Variables are officially supported to be used in the following locations:
    • As a channel number in a channel command, or a part of it
    • As a note, rest, chord or percussion ID in a channel command, or a part of it
    • As a length description in a channel command, or a part of it
    • As an option value (or a part of it) in any command that supports options

In all other locations you should not use variables. They may work or not. But even if they work, they may not work in a later Midica version any more.