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 about lowlevel commands, 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 soundbanks.

Lowlevel Channel Commands

In newer Midica versions, lowlevel commands are not needed any more. If you are not interested how to use them, you can skip this section.

The channel commands from the last chapter are compact channel commands. Compact means, you can play several notes, chords or rests in a single line. There is also another kind of command called lowlevel channel command, allowing only one note or chord or rest per line.

In earlier Midica versions there were some things you could not express with compact commands. But since version 1.5.4 the compact commands support everything that lowlevel commands support.

Still it is useful to know that lowlevel commands exist, and how they look - at least for one reason: If you forget the : after the channel number of a compact command, Midica may think that you tried to use an illegal lowlevel command. And then the resulting error message could be confusing.

A lowlevel channel command consists of at least 3 columns, separated by whitespaces:

1. Channel column
2. Note column
3. Length column
4. (Optional) After the 3rd column one or more options may follow. Details will be described later in this chapter.

The following example shows "Happy birthday to you" on channel 0 again, but this time written with lowlevel commands.

Mixing Compact and lowlevel commands

Both channel command types can be mixed, like the following example demonstrates:

The note length definition of a lowlevel command does NOT change the default note length of a compact command!

So in the last line the default is still a 16th note, and we have to switch to a 4th explicitly. Even if there have been other 4th notes in the lowlevel commands in line 2 and 3.

Channel Options

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. Until the option is used in the same channel again, with a different value.

The following example shows how to use velocity, first with compact and then with lowlevel commands.

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

It also shows that whitespaces and the = is optional in lowlevel commands. But compact commands are stricter. Here you cannot use any whitespaces between the parenthesis, and the = is mandatory.

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 length. 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 higher 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.

The following example shows a compact and a lowlevel version of the same sequence with duration changes:

The last two notes have a change of duration as well as a change of velocity. Two options can be changed together. But in the compact version no whitespaces are allowed.

Quantity

The quantity option repeats a command any number of times. The option name is quantity. The short form is q.

In compact syntax, the command affects the next compact note or chord or rest after the option in the same channel.

The following example shows the beginning of "The Four Seasons: Summer", 3rd movement, by "Antonio Vivaldi". It uses a violin in channel 0 and a harpsichord in channel 6. (Please update your INSTRUMENTS block accordingly.) The first example is a compact version, the second one is a lowlevel version of the sequence.

Here is another example of the same sequence in compact syntax:

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.

In compact syntax, the command affects the next compact note or chord or rest after the option in the same channel.

As we already know, each note (or chord or rest) is added to the end of a channel. To be more precise, it's added 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 we use the multiple option, the marker is not moved. So the next note that is added to the channel, begins at the same time as the note with the multiple option.

The following example demonstrates this, first with compact and then with lowlevel syntax, producing the same sequence:

This example shows some possibilities to use the multiple option. The first bar uses 2 voices, shown as blue and black. The full note (c) 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 last screenshot shows how the result looks inside of the player in karaoke mode.

Tremolo

0: (tremolo=8) c:1
1: (tr=16) c,e:1
2: (tr=8) c (tr=16) c:8 (tr=32) c
p: (tr=32) bd1:1

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

0: (q=8) c:8
1: (q=16) c,e:16
2: (q=2) c:8
2: (q=2) c:16
2: (q=4) c:32
p: (q=32) bd1:32

Shift

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

CHORD cmaj c,e,g
0  c     4
0  e     4
0  b-    4
0  e,g   4
0  cmaj  4

Length

0: (length=8.) c (length=16) c
0: (length=4) d c f (length=2) e

0: c:8. c:16
0: d:4 c f e:2

Length Definitions

So far we learned where we can define note lengths:

• In compact commands: after the note name, separated by a colon (:)
• In a lowlevel command: in the 3rd column
• In compact commands: as the value of a length option
• In any command: as the value of a tremolo option

And we know how to define the most frequently used note lengths. Now let's see how to compose all possibilities of lengths.

The easiest length is an atomic length. It can be modified by one or more modifiers to create a modified length. And last but not least you can combine two or more atomic or modified lengths to form a sum of lengths.

Atomic Lengths

You can just use an integer number as a note length. The resulting length corresponds to a full note's length divided by that number. This is one kind of atomic length.

Apart from this, there are also the following predefined atomic lengths:

/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)

This makes atomic note lengths available that are longer than a full note - those beginning with *.

The shorter notes (beginning with /) are not really needed as they can be replaced by just the number without the prefixed /. However they can make lowlevel commands a bit more readable. But in compact commands they look quite cumbersome, so you probably don't want to use them there.

From now on we will use predefined notes in lowlevel commands and (if possible) just numbers in compact commands.

The first example uses compact commands and only numbers, if possible. In channel 0 only a predefined length is possible.

The second example uses lowlevel commands and only predefined lengths, if possible. For the last two notes only numbers are possible because a 64th note is so rare that it has no predefined version.

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.

Here is a compact and a lowlevel example showing how dots can be used:

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.

Here is a compact and a lowlevel example showing how triplets can be used:

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.

Here is a compact and a lowlevel example showing how tuplets can be used:

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" with compact commands.

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

More complicated expressions are also possible like /2.+/1+/2t. Here is a lowlevel example:

Zero-Length

There is one special length symbol: -. It means "no length at all". Of cause this does not make sense for any normal note, chord or rest. However it can be is useful to change a channel option in a lowlevel command without playing a note or chord.

In compact commands it does not make any sense at all, however.

The zero-length is only allowed in combination with a rest but not with a note or chord. So the second and third column both have the symbol -.

The following examples are equivalent:

0  -  -   v=95, d=50%
0  c  /4
0  d  /4
0  -  -   v=50, d=100%
0  e  /4
0  f  /4
0  -  -   v=95
0  g  /4
0  a  /4

0  -  /4  m, v=95, d=50%
0  c  /4
0  d  /4
0  -  /4  m, v=50, d=100%
0  e  /4
0  f  /4
0  -  /4  m, v=95
0  g  /4
0  a  /4

0  c  /4  v=95, d=50%
0  d  /4
0  e  /4  v=50, d=100%
0  f  /4
0  g  /4  v=95
0  a  /4

The first example uses zero-length rests to change the velocity and duration of the following notes.

The second example uses real rests, but with m as additional option. This is an alternative for zero-length rests.

The third example doesn't use rests at all but applies the channel parameters directly to a note.

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".

The first example uses lowlevel commands and long percussion IDs. The second one uses compact commands and 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".

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 Soundbanks

Include Soundbank File

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

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

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

Of cause a local file path does not work on someone else's computer because he will probably not have the same soundbank in the same directory inside of his file system. Therefore you can reference the file by URL.

But URLs contain a double slash //, that is also the comment symbol in MidicaPL. For this reason the two slashes in the URL must be separated by a space.

Referencing a soundbank by URL like this works on other computers as well. However it will still not work in an exported MIDI file because soundbank 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 soundbanks 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 soundbanks 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 soundbanks 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 soundbank.

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:

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:

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 soundbank 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.

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's value 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 might not work in a later Midica version any more.

Bar Lines

In compact syntax you can simulate a bar line using the pipe symbol: |.

Using bar lines is optional. But if they are used, they must be in the correct place. Whenever you use a bar line, Midica will check if the channel's current position is at the border of a measure. Otherwise it will show an error message.

The check works like this:

• It searches the last global command with a time signature and calculates how long each following measure must be. If no such command has ever been used, it pretends that a time signature of 4/4 has been set at the very beginning of the sequence. (Like with the command * time 4/4)
• It measures the length from the position of the last time signature (or the very beginning, if none is found) until the current position.
• It checks if the result can be divided by a measure length.

This is a convenient way to check if everything is correct. The following example shows Happy Birthday with time signatures and bar lines:

This time we used the time signature twice: once for the upbeat and then again when the regular measure starts. If we would omit the first two bar lines, then we could also omit the time signature for the upbeat in line 1. But it's still important to set the 3/4 time signature directly after the upbeat - and not at the beginning. Otherwise the bar lines in the last line would fail.

Bar Line Tolerances

Most of the time you will not need anything more to know about bar lines. But there are special cases, mostly when you use complicated tuplets. Then a note length may be not really exact, due to rounding errors. And this results in bar lines that are set correctly but fail anyway. The following example shows a score with a nested triplet and the intended result:

However the second bar line (marked in red) fails with an error message. Why?

A MIDI timeline consists of very small atomic units called ticks. Midica uses a resolution of 480 ticks per quarter note. A quarter note in a nested triplet would have 480 * 2/3 * 2/3 ticks. That's 213 + 1/3. But broken ticks are not possible. So this is rounded to 213. The three nested quarter notes together have a length of 213 * 3 = 639 instead of their theoretically correct value of 640.

To circumvent this problem you can set a tolerance value for a barline. This is a number that you just attach to the barline directly, without any whitespace. To set a tolerance of 3 ticks, you would use: |3.

For our example, a tolerance of 1 tick is sufficient, as the following, now working example shows:

The first bar line has the default tolerance, which is 0. In the second bar line (marked in blue) we set the tolerance to 1.

The third bar line succeeds as well - even if we would probably expect it to fail.

The reason is that |1 sets the tolerance not only for the second bar line but also for all following bar lines in the same channel.

That's a very convenient way to reduce the need to set tolerances. Mostly we can just write |.

Global Change of Bar Line Tolerances

If we use several channels, we want to synchronize them with * from time to time. In this case we may need to apply a tolerance to all channels.

The following example shows a score with a septuplet and the intended result. The second bar line in channel 0 needs a tolerance of 2, marked in blue. In line 3, we syncronize (*) the channels to avoid the need to write an explicit rest in channel 1. However in channel 1 the barline marked in red fails:

The reason is that after the sync * in line 3, the bar lines in channel 1 also need a tolerance. One possible solution is to change the bar line marked in red from | to |2. But that's unconvenient and ugly, especially if we have more channels than 2.

A better solution is to modify the sync command to set a tolerance globally. Therefore we add two columns to the sync command, each one separated by whitespace(s). The first one ist the bar line symbol |, the second one is the new global tolerance value.

In this case, we want to set a tolerance of 2 for all channels, so we write * | 2, as the following example demonstrates:

This time we don't get an error message any more.