MidicaPL Tutorial, Chapter 1: Basics

This is the first chapter of the MidicaPL tutorial, teaching the basics of the language. If you did not yet follow the preparation instructions, please do so before you continue reading.

At the end of this chapter you will be able to create melodies with notes, chords and rests using different instruments playing together. Moreover you will learn how to change the tempo of your music.

Whitespaces and Comments

Each line of the source code can either be empty or contains a command or a comment or both. Comments are prefixed by the symbol // and end at the end of the line. Empty lines and comments are ignored. Whitespaces at the beginning or end of a line are also ignored. More than one whitespace has the same effect as one single whitespace.

So the next two source code examples are equivalent.

MidicaPL
// define an instrument
INSTRUMENTS        // open block
	0	2	Piano
END                // close block

// define some chords
CHORD    c_maj     c  e  g
CHORD    d_maj     d  f# a

CHORD    f_maj     f  a  c
// end of chord definitions
MidicaPL
INSTRUMENTS
0 2 Piano
END
CHORD c_maj c e g
CHORD d_maj d f# a
CHORD f_maj f a c

Instrument Definition Block

Before you can play any sounds, you must define the instruments to be used by each channel. Every channel that will be used later must be initialized inside of a block beginning with INSTRUMENTS and ending with END.

The only exception is the percussion channel (channel 9) which may (but does not need to) be defined explicitly.

MidicaPL
INSTRUMENTS
	0	ELECTRIC_GRAND_PIANO	Piano
	1	VIOLIN					Fiddle
	2	32						Bass
	p	STANDARD				Standard Drumkit
END

Each line inside of this block contains 3 columns, separated by one or more whitespaces. The last column may also contain more whitespaces. These are not interpreted as separator but as a part of the content.

1st column

The first column contains the chanel number. Valid values are the numbers 0 - 15 and the symbol p.

p is just an alias for 9 which is the percussion channel number.

2nd column

The second column describes the instrument. It may contain a valid instrument ID or drumkit ID or the accoring MIDI program number.

Valid instrument or drumkit IDs can be found in the info window under Configuration

3rd column

The third column contains a description of the instrument. This will be displayed as a channel comment in the player.

In the above example we use an instrument ID for the channels 0 and 1, a MIDI program number for channel 2, and a drumkit ID for channel 9.

The line defining the percussion channel (p) is optional. If it is omitted, the standard drumkit (MIDI program number 0) is used.

Channel commands

After you have defined some channel instruments, you can use channel commands in order to play music. The most important things to do with channel commands is playing notes, chords or rests.

Channel commands consist 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 in chapter 2. Please be patient.

The following example shows the first notes of "Happy birthday to you" on channel 0.

MidicaPL
0	c	/8	// hap-
0	c	/8	// py
0	d	/4	// birth-
0	c	/4	// day
0	f	/4	// to
0	e	/2	// you
Result (Score)

Channel column

This column contains the chanel number. Valid values are the numbers 0 - 15 and the symbol p. Again, p is an alias for 9 (percussion channel).

Note column

This column can contain a note name, a percussion ID, a chord name or the symbol - which stands for a rest (pause). Additionally you can also use the MIDI note number.

Length column

This column contians a length definition. A full, a half, a quarter, an eighth note and so on is defined like /1, /2, /4, /8 and so on. For dotted notes a . is added (but without any whitespace between). More details about length definitions will follow in chapter 2.

The following example shows another version of "Happy birthday to you" but with a rest instead of "day", so that it's actually only "Happy birth... to you".

MidicaPL
0	c	/8.	// hap-
0	60	/16	// py
0	d	/4	// birth-
0	-	/4	// ... (rest)
0	f	/4	// to
0	e	/2	// you
Result (Score)

The first eighth note is now dotted, so that the length is 1.5 times longer. Therefore the second note is only a 16th.

The pitch of the first two notes is equivalent. Both are a middle C. But in the first line the note name c is used, and in the second line the MIDI note number 60.

Note Names

Which note names are valid, depends on the configured note system, half tone symbol and octave naming. In the standard configuration, lower-cased international note names are used, and the half tone symbols are # for a sharp and b for a flat. Then follows an octave modifier.

The octave beginning with the middle C is not modified.

Higher octaves are modified with +, +2, +3 and so on.

Lower octaves are modified with -, -2, -3 and so on.

The following example shows the first bar of "Through the Never" by "Metallica", played in channel 1.

MidicaPL
1	e-2		/8
1	f#-2	/8
1	c#-		/8
1	f#-2	/8
1	e-2		/8
1	f#-2	/8
1	c#-		/8
1	f#-2	/8
Result (Score)

Double sharps (##) or double flats (bb) are also possible, like these:

  • f## (same as g)
  • f##+ (same as g+)
  • f##+2 (same as g+2)
  • dbb (same as c)
  • dbb+3 (same as c+3)
  • cbb+3 (same as bb+2 or a#+2)

Using multiple channels

Different channels can play notes at the same time. Each channel command appends a note (or something else) to the end of a channel. So the order of channel commands for the same channel is important. But the order of commands for different channels does not matter.

The following examples are equivalent. They play the first two bars of "Jingle Bells".

MidicaPL
// channel 0
0	e	/4
0	e	/4
0	e	/2
0	e	/4
0	e	/4
0	e	/2

// channel 1
1	c-	/2
1	g-	/2
1	c-	/2
1	g-	/2
MidicaPL
// channel 1
1	c-	/2
1	g-	/2
1	c-	/2
1	g-	/2

// channel 0
0	e	/4
0	e	/4
0	e	/2
0	e	/4
0	e	/4
0	e	/2
MidicaPL
// 1st bar
0	e	/4
1	c-	/2
0	e	/4
0	e	/2
1	g-	/2

// 2nd bar
0	e	/4
1	c-	/2
0	e	/4
0	e	/2
1	g-	/2
Result (Score)

The first example adds all notes to channel 0 before adding all notes to channel 1.

The second example begins with channel 1 and then handles channel 0.

The third example works more or less in the order of appearance of the notes in time. Of cause this is not always possible because some notes are played simultaniously but two channel commands cannot be written into the same line of source code.

Chords

A chord in MidicaPL is an amount of notes to be played at the same time in the same channel, with the same length and velocity. There are 2 types of chords: inline chords and predefined chords.

Inline Chords

An inline chord is a number of note names in the second column of a channel command, separated by a ,. There are no whitespaces allowed between the notes.

The following example shows the beginning of Bob Marley's song "No Woman No Cry".

MidicaPL
1	c,e,g    /1
1	g-,b-,d  /1
1	a-,c,e   /1
1	f-,a-,c  /1

0	-        /2
0	c+       /2
0	b        /4
0	c+       /4
0	b        /4
0	a        /4
Result (Score)

The piano is played in channel 1 using inline chords. The singer's voice is played in Channel 0 without chords.

Predefined Chords

In order to use a predefined chord, the chord must be defined somewhere. Usually a chord definition consists of 3 or more columns, separated by whitespaces.

The first column is the keyword CHORD. The second column is a self-given chord name. The other column(s) contain the notes belonging to that chord, one note by column. The notes can be separated either by , symbols or whitespaces or both.

Between the chord name and the notes, you may optionally add a = instead of (or as well as) whitespaces. The following examples are all similar chord definitions:

  • CHORD c-maj c e g
  • CHORD c-maj c,e,g
  • CHORD c-maj=c,e,g
  • CHORD c-maj = c, e, g
  • CHORD c-maj = c , e , g

Predefined chords can be used like normal notes inside of a channel command. But instead of the note name, the self-given chord name is used.

The following example shows the same notes again but this time with predefined chords instead of inline chords.

MidicaPL
CHORD c-maj c, e, g
CHORD g-maj g-,b-,d
CHORD a-min a- c  e

1   c-maj  /1
1   g-maj  /1
1   a-min  /1
1   f-maj  /1

0   -    /2
0   c+   /2
0   b    /4
0   c+   /4
0   b    /4
0   a    /4

CHORD f-maj f- a- c
Result (Score)

As you can see in this example, the chord doesn't need to be defined before using it. It can also be defined later, like the f-maj chord here.

Imagine you use the same chord (e.g. C-major) many times in a song. And then you want to modify the chord (e.g. transform it into C-maj-7). With predefined chords you only need to change the chord definition while with inline chords you need to change every appearance.

Global Commands

While channel commands only affect one channel, there are also global commands that affect more than one channel. Most of them even affect all channels. A global command begins with the symbol * in it's first column.

Synchronize

Every global command syncronizes all (or at least some) channels. That means the current channel lengths are made equal to the furthest channel's length. A global command adds an according amount of rests to all other channels. So many that all synchronized channels have the same length as the furthest channel.

This behaviour can be very helpful. So even a global command without any further options can be useful. This empty form of a global command is called synchronize command because it's only purpose is to synchronize all channels.

The following example shows the first 2 bars of "The Black Perl" by "Klaus Badelt" from the film "Pirates of the Carribean: The Curse of the Black Perl".

MidicaPL
1  d-  /8
0  d   /8
0  -   /8
0  d   /8
0  eb  /8
0  d   /8
0  eb  /8
*
1  d-  /8
0  d   /8
0  -   /8
0  d   /8
0  eb  /8
0  d   /8
0  eb  /8
*
Result (Score)

Channel 1 contains a lot of rests but none of them is written with a channel command. The rests are added implicitely by adding a synchronize command at the end of each bar.

Partial Synchronize

If you want to synchronize only a part of the channels, you can use a partial synchronize command. This is the only global command that does not synchronize all channels but only some of them. In the second column of a partial synchronzie there is a description which channels should be synchronized.

This description can be a comma-separated list of channel numbers (e.g. 1,2,3) or a range like 1-3) or a mix like 1-3,5,6-8,11.

You can use the symbol p for channel 9 here as well.

MidicaPL
*	1-3,5,p,12-14

This example synchronizes channels 1, 2, 3, 5, 9, 12, 13 and 14 with each other.

The partial synchronize is the only global command that synchronizes only a part of the channels. All other types of global commands always synchronize all channels.

Set Tempo

Another important global command is a tempo change. The tempo is defined in "beats per minute" (BPM). The second column of the global command contains the symbol tempo and the third column the desired value.

The value is the number of quarter notes that is played in one minute. The default value is 120. It could be changed to 150 using the following command:

MidicaPL
*  tempo  150

Like every other global command, a tempo change synchronizes all channels.

The following global commands ("time signature" and "key signature") are not audible. They only add meta information to the MIDI sequence. If you are only interested in hearable commands, you can continue directly with chapter 2.

Set Time Signature

The time signature can be set with the time command in the second column. The third column contains the desired time definition.

The time definition contains a nominator (number) and a denominator, separated by a /.
The MIDI default is a 4/4 beat.
A 3/4 beat would be defined like this:

MidicaPL
*	time	3/4

The denominator must be a number that can be described as 2n. That means valid denominators are 1, 2, 4, 8, 16, 32, etc.

The time signature does not change the sound of the MIDI sequence at all. However it can make sence to define it anyway. It can be a useful hint for third-party software processing the MIDI file exported by Midica.

Set Key Signature

The key signature can be set with the key command in the second column. The third column contains the desired key definition.

The key definition contains a valid note name and a tonality, separated by a /.
The tonality can be maj for major or min for minor.
The MIDI default is C major, which could also be defined explicitely by the following command:

MidicaPL
*	key   c/maj

What a valid note name is, depends on the configured Note System, Half Tone Symbol and Octave Naming. In the standard configuration a C# minor could be set with one of the following commands.

MidicaPL
*	key   c#/min
MidicaPL
*	key   c#-2/min
MidicaPL
*	key   c#+4/min

Of cause these commands are equal because the octave is irrelevant for the key signature.

Like the time signature, the key signature does not change the sound at all. But it can also be useful for another software processing the produced MIDI sequence.

Internally the key signature is translated into a number of sharps or flats and a flag for major or minor. Midica tries to be as close as possible to the intended key signature. But MIDI has a limitation that allows a maximum of 7 sharps or flats. So in some cases the key signature is converted automatically to something corresponding.

For example a D# major would have 9 sharps which is more than the allowed 7. So it's converted to the corresponding Eb major with 3 flats instead.