Mutabor Tutorial

Lets start with a simple tuning logic. Open a new file in your favourite editor. (At the time of writing this text this propably won't be Mutabors integrated one.) Save it under the name "minimal.mut".

Now start Mutabor. It should greet you with the route editor window. If you didn't use Mutabor so far it will be empty except three buttons named “New input device”, “New Box” and “New output device”. A double click on “New input device” will open a dialog.

Choose the device, where your keyboard is connected to and click ok. With a double click on “New output device” you can select the output device.

For MIDI files and devices you have to input the pitch bend range according to the settings of your device. Most devices initially have selected 2 semitones. Click on “OK”.

After selecting the devices double click on “New Box”. A new dialog will appear, that allows you to wire the input devices, the logic and the output devices according to your needs.

Click on “Add route”. A new row will of controls will appear. On the left hand side select your input device. The filter setting should remain at “all”. On the right hand side select your output device and select “all” for the filter settings.

On top select “Mutabor box”, leave the box number unchanged and click “Ok”.

Via File->Open you can open the file “minimal.mut” and click on the green traffic light, in order to start it.

Now several windows appear and when you press any key on your MIDI keyboard, there should be some sound. Congratulations you set up Mutabor correctly.

The minimal tuning logic has already been described by the empty file. Now, we will discuss a simple non-trivial tuning logic. The syntax for such a tuning is the following:
LOGIC definitions
The definitions are separated by spaces. Each of these definitions has the form
name KEY character = initial_tuning [ commands ]

The parameters are the following:

name

An arbitrary name, which consists of letters, numbers and the signs “'” and “_”

character

The key that has to be pressed on the computer keyboard in order to activate the logic

initial_tuning

The initial tuning that will be loaded, when this logic is activated

commands

A list of triggers and actions that describe the behaviour of the logic, we leave it empty for now

The simplest tuning is an equal tempered tuning. Lets assume we want a 12 tone equal temperament (12tet). So, we call the logic “equal” and want to activate it using the letter “e”. The tuning will be 12tet. Since names must not start with a digit, we will use the name “equal tempered 12 tone”, in short “et12t”. So the logic definition looks like
LOGIC
equal KEY e = et12t []

Trying to compile this tone system produces an error message. We have to define the tone system “et12t” first. A tone system is defined according to
TONESYSTEM definitions
The definitions are seperated by spaces. Each of them has the form
name = anchor key [ fundamental scale ] repetition interval
The parameters are defined as the following:

name

An arbitrary name, which consists of letters, numbers and the signs “'” and “_”

anchor key

a number between 0 and 127, which defines the MIDI code of the lowest piano key of the so called fundamental scale, the middle C has number 60 and the corresponding tone the number 69

fundamental scale

a comma separated list of tone names

repetition interval

the repetition interval is a name or interval expression, which will be used for repetition of the fundamental scale

As you can see, one important thing is the fundamental scale. It is a list of tones, which will be repeated throughout the whole MIDI pitch space, which spans integers from 0 to 127. Each repetition will be transposed with respect to its predecessor by the repetition interval. An empty tone denotes a silent key.

We choose the tone A' for the anchor key, which is usually tied to key 69. You can play with this number if you want to transpose your piece of music. Since we choose to define an equal tuning, we need only this single tone and the repetition interval, which is a half tone.

So our tuning logic looks like:
LOGIC
equal KEY e = et12t []
TONESYSTEM
et12t = 69 [ A' ] half_tone

This logic is still not complete. We have to define the tone A' and must tell Mutaber what is meant by half_tone. Lets start with the tone A'. The easiest way to define it, is to assign a frequency to it. The syntax is as simple:
TONE definitions
where definitions is a list of tone assignments separated by spaces. The frequency assignment has the syntax:
name = frequency
Here the parameters are defined as:

name

An arbitrary name, which consists of letters, numbers and the signs “'” and “_”

frequency

a number that corresponds to the frequency in Hertz

Later we will use other description for tones.

We assign the tone A' to its usual frequency of 440 Hz and get the following logic:
LOGIC
equal KEY e = et12t []
TONESYSTEM
et12t = 69 [ A' ] half_tone
TONE
A' = 440

At last we have to define the repetiton interval. The syntax for intervals is as simple:
INTERVAL definitions
where definitions is a list of interval assignments separated by spaces.
Each interval must be defined according to the syntax:
name = interval expression
Here the parameters are defined as:

name

An arbitrary name, which consists of letters, numbers and the signs “'” and “_”

interval expression

a description of the interval

There are several intuitive descriptions of intervals possible. We will use the syntax:number1 ROOT number2 which denotes the number1st root of number2 as factor in frequency range. For the 12 tone equal temperament (12tet) we have to choose the 12th root of 2.

Using this we get the following logic:
LOGIC
equal KEY e = et12t []
TONESYSTEM
et12t = 69 [ A' ] half_tone
TONE
A' = 440
INTERVAL
half_tone = 12 ROOT 2

Congratulations. You have written your first non-trivial tuning logic. Start the logic now, and you should get a window that allows you to click on exactly one icon.

Click on that icon to activate the tuning:

Now you can play some notes on your keyboard.

The given logic description is one of the most simple descriptions in the sense of syntax. But there are descriptions, which are much more intuitive. For instance we could base our half tone on the octave:
half_tone2 = 1/12 octave
octave = 2:1

The second line follows the pattern name = number:number which assign frequency ratios to intervals. So one tone is an octave heigher than another, if it has twice the frequency of the latter one. The first line follows our intuition that each octave is equal in size to all other octaves and can be devided into equal parts. It defines a second half tone to be exactly one twelveth of an octave. Formally this can be understood as an instance of name = number/number name2 where name2 denotes an interval that is defined elsewhere (e. g. in the next line).

Having that in mind we can define a second tonesystem et12t2 by adding the code:TONESYSTEM
et12t2 = 69 [ A' ] half_tone2
INTERVAL
half_tone2 = 1/12 octave
octave = 2:1

But we don't want to replace the logic without checking that it is correct. So we must compare the two tunings. One easy way is to define two keyboard events for our logic. Remember, we hat defined the logic according to name KEY character = initial_tuning [ commands ] and left the command section empty. Since the two tunings are virtually equal it is a good idea to group them together. This can be done by defining two keybord events which call the korresponding tungings:
LOGIC
equal KEY e = et12t [
KEY m -> et12t
KEY i -> et12t2
] Here each letter event calls a fixed tuning. The syntax of one trigger is
KEY character = { action list } were character denotes a character and
action list describes which actions shall be executed when the corresponding event occurs. The braces can be omitted if action list constists only of one action. The keyword KEY denotes a key on the computer keybard. We have chosen the keys “m” like “mathematical” and “i” like “intervallic”. The complete logic looks like

LOGIC
equal KEY e = et12t [
KEY m -> et12t
KEY i -> et12t2
]
TONESYSTEM
et12t = 69 [ A' ] half_tone
TONE
A' = 440
INTERVAL
half_tone = 12 ROOT 2
TONESYSTEM
et12t2 = 69 [ A' ] half_tone2
INTERVAL
half_tone2 = 1/12 octave
octave = 2:1

As you can see, we can have each section multiple times in the logic program. This is helpful when we want to have all realated definitions as close as possible in the tuning logic.

Now you can load and start your logic with the semaphore button as described above. When you select a MIDI program (instrument) that produces stable tones like an organ, you will easily be able to compare the tunings.

As you can see there are two additional icons, now. These are the computer keyboard events of your logic. They can be selected either by pressing the denoted key or by clicking on it. Select one by clicking on it, press a key and hold it down while you click the other tuning. You can see that the note on the icon will follow your click. It shows the active tuning. If you hear changing anything, then the two tunings differ. You can try to find out how much you can recognize by playing with the numbers in your logic. Change for example the ratio 1/12 into 12/143. You will be surprised, how easy it is to hear the changes.

Now we have enough knowledge to write some unusual tunings. One important musical concept is the circle of fifth. In ancient times it was used as the foundation of our current tone systems. On a piano it is the interval betwen D and A or A and E. If you count the keys, you can see that there are 6 keys or 7 half tones between them. If you ignore the octave there are 12 different fifth. These form the circle of fifth. If you want to listen to it you can play it. If you are not familiar with a piano keyboard, we can help out to make it even easier to play it: We can define a tone system, that has a fifth instead of the half tone:

LOGIC
equal KEY e = et12t [
KEY m -> et12t
KEY i -> et12t2
]
TONESYSTEM
et12t = 69 [ A' ] half_tone
TONE
A' = 440
INTERVAL
half_tone = 12 ROOT 2
TONESYSTEM
et12t2 = 69 [ A' ] half_tone2
INTERVAL
half_tone2 = 1/12 octave
octave = 2:1
LOGIC
fifth KEY f = et12fifth [
KEY j -> justfifth
]
TONESYSTEM
et12fifth = 69 [ A' ] 7 half_tone
justfifth = 69 [ A' ] just_fifth
INTERVAL
just_fifth = 3:2

As you can see we have added a new logic with a KEY event. The logic tunes to 12tet fifth and when you press the letter “j”, it retunes to the system of just fifth which are nearly perfectly tuned to our usual instruments: strings, winds, brass. Again you can compare the two tunings.

In order to make a tone system or pitch space from these tones, firstly, we must map them into one octave. This means, we have to define further tones:

TONE
E' = A' + just_fifth - octave
B' = E' + just_fifth
Fis' = B' + just_fifth - octave
Cis' = Fis' + just_fifth - octave
Gis' = Cis' + just_fifth
D' = A' - just_fifth
G' = D' - just_fifth + octave
C' = G' - just_fifth
F' = C' - just_fifth + octave
Bes' = F' - just_fifth + octave
Es' = Bes' - just_fifth
As' = Es' - just_fifth + octave
" ... "

The quotes “"” at the bottom delimit a comment. As you can see, we had to correct the pitch seven times by one octave. We usually replace As' by Gis' when we talk about music. In fact, there is a distance of one 5th of a half tone between them. So this enharmonic replacement would violate our rules. In order to be able to start the circle of fifth at any position, we choose the repetition interval such that all fifth are tuned just:

TONESYSTEM
circleoffifth = 63 [ Es', Bes', F', C',G',D',A',E',B',Fis',Cis',Gis' ] 12 just_fifth - 7 octave

When we want to play using one of the oldest such tuning systems, the Pythagorean tuning, we must rearrange the tones and will repeat this system shifted by an octave:

TONESYSTEM
pythagoras = 60 [ C', Cis', D', Es',E',F',Fis',G',Gis',A',Bes',B' ] octave

Let's add them to our tuning logic:LOGIC
equal KEY e = et12t [
KEY m -> et12t
KEY i -> et12t2
]
"12 tone equal temperament (12tet)"
TONESYSTEM
et12t = 69 [ A' ] half_tone
TONE
A' = 440
INTERVAL
half_tone = 12 ROOT 2
"12 tone equal temperament (alternative definition)"
TONESYSTEM
et12t2 = 69 [ A' ] half_tone2
INTERVAL
half_tone2 = 1/12 octave
octave = 2:1
LOGIC
fifth KEY f = et12fifth [
KEY j -> justfifth
KEY c -> circleoffifth
KEY p -> pythagoras
]
"12tet and just fifth"
TONESYSTEM
et12fifth = 69 [ A' ] 7 half_tone
justfifth = 69 [ A' ] just_fifth
INTERVAL
just_fifth = 3:2
TONE
E' = A' + just_fifth - octave
B' = E' + just_fifth
Fis' = B' + just_fifth - octave
Cis' = Fis' + just_fifth - octave
Gis' = Cis' + just_fifth
D' = A' - just_fifth
G' = D' - just_fifth + octave
C' = G' - just_fifth
F' = C' - just_fifth + octave
Bes' = F' - just_fifth + octave
Es' = Bes' - just_fifth
As' = Es' - just_fifth + octave
" ... "

"spiral of fifth an Pythagorean tuning"
TONESYSTEM
circleoffifth = 63 [ Es', Bes', F', C',G',D',A',E',B',Fis',Cis',Gis' ] 12 just_fifth - 7 octave
pythagoras = 60 [ C', Cis', D', Es',E',F',Fis',G',Gis',A',Bes',B' ] octave

Try to play all fifth in the tone system named “pythagoras”. You will one fifth that is very ugly.

Now, it's time to head over to one of the best strengths of Mutabor: mutable tunings.

We will fix one of the drawbacks of the pythagorean tuning: The bad fifth. For that we must define some rules which tell Mutabor, how to react on which events. Mutabor can recognize keys, harmonies, harmonic forms (all shifted versions of one pattern) and MIDI events. For now, it is sufficient to react on a harmonic form. As the Pythagorean tuning is based on a just fifth it would be nice, if each fifth could be just. This can be achieved, when we shift the interval structure to the actual active tones.

Lets start to explain it to Mutabor:
PATTERN
fifth = {0, *3, *4, 7,*9}

This defines the pattern “fifth” as the combination of a reference key (0) and the fifth above it (7). Optionally, the keys 3, 4 and 9 can be pressed, as denoted by the asterisk “*”.

The retuning will be defined by
RETUNING
transpo (distance) = @+distance []
This defines a retuning named “transpo”, which takes one parameter named “distance”. The name “distance” is one of the two parameters that have a special meaning. It tells the retuning the distance between the anchor key of the pattern (denoted by number 0) and the anchor key of the fundamental scale. The right hand site denotes the action. In this case it is a change of the anchor key of the tuning. The at sign “@” denotes the current anchor and the expression tells how to change it. Here, we move it to the anchor key of our pattern. This instructs Mutabor to move the fundamental scale from the old anchor key to a new one, transposing it so that from the old anchor tone the old pitch of the new anchor tone. So the latter one is never changed, while all the other tones might get assigned to a new frequency.

There are several different possibilities for defining such retunings. For further information we refer to the reference manual.

To finish our tuning, we must define a logic:

LOGIC
adaptive KEY a = pythagoras [
SHIFTED fifth -> transpo(distance)
]

The keyword “SHIFTED” denotes that the pattern is recognized in any transposition and that the parameter “distance” is set according to this transposition.

Finally, we can put everything together and get the following tuning logic:
TONESYSTEM
pythagoras = 60 [ C', Cis', D', Es',E',F',Fis',G',Gis',A',Bes',B' ] octave

Let's add them to our tuning logic:LOGIC
equal KEY e = et12t [
KEY m -> et12t
KEY i -> et12t2
]
"12 tone equal temperament (12tet)"
TONESYSTEM
et12t = 69 [ A' ] half_tone
TONE
A' = 440
INTERVAL
half_tone = 12 ROOT 2
"12 tone equal temperament (alternative definition)"
TONESYSTEM
et12t2 = 69 [ A' ] half_tone2
INTERVAL
half_tone2 = 1/12 octave
octave = 2:1
LOGIC
fifth KEY f = et12fifth [
KEY j -> justfifth
KEY c -> circleoffifth
KEY p -> pythagoras
]
"12tet and just fifth"
TONESYSTEM
et12fifth = 69 [ A' ] 7 half_tone
justfifth = 69 [ A' ] just_fifth
INTERVAL
just_fifth = 3:2
TONE
E' = A' + just_fifth - octave
B' = E' + just_fifth
Fis' = B' + just_fifth - octave
Cis' = Fis' + just_fifth - octave
Gis' = Cis' + just_fifth
D' = A' - just_fifth
G' = D' - just_fifth + octave
C' = G' - just_fifth
F' = C' - just_fifth + octave
Bes' = F' - just_fifth + octave
Es' = Bes' - just_fifth
As' = Es' - just_fifth + octave
" ... "
"spiral of fifth an Pythagorean tuning"
TONESYSTEM
circleoffifth = 63 [ Es', Bes', F', C',G',D',A',E',B',Fis',Cis',Gis' ] 12 just_fifth - 7 octave
pythagoras = 60 [ C', Cis', D', Es',E',F',Fis',G',Gis',A',Bes',B' ] octave
"Mutable tuning: moving fifths."
PATTERN
fifth = {0, *3, *4, 7,*9}
RETUNING
transpo (distance) = @+distance []
LOGIC
adaptive KEY a = pythagoras [
SHIFTED fifth -> transpo(distance)
]

The logic above contains most of the concepts, which are useful for writing static tunings and for simple mutable tunings. The pythagorean tuning can be used as a basis for a Tonnetz based tuning as atonal just intonation (see e. g. Demo_en.mut, or the Wiki pages of Mutabor).

Mutabor has far more capabilities. It is possible to write even some tunings with Mutabor.