Settings Overview

Fundamental Mother

The first parameter is the “main root” and it’s called FUNDAMENTAL MOTHER (abbreviated is FM). This is the main tone on which all other tones are calculated.

The default value is C3 (or the first C below the middle C) that is the MIDI note 48 (MIDI cent) or frequency 130.813 Hertz.

In the note name, the number (in this case 3) indicates the octave in the scientific pitch notation.

You can set the FUNDAMENTAL MOTHER in two ways:

MIDI note number:

1. select MIDI NOTE (0-127) on the right switch
2. enter the MIDI note number (from zero to 127) in the grey text box
3. press enter

Frequency:

1. select FREQUENCY (Hz) on the right switch
2. enter the frequency (in Hertz) in the grey text box
3. press enter

Note that you can write decimal values. The decimal mark is the point [ . ]

• The decimals used with MIDI note number are intended as cents above of that note. For example:
  – writing 48.5 means: MIDI note 48 + 50 cents
  – writing 48.61 means: MIDI note 48 + 61 cents

• The decimals used in the frequency are normal decimals. For the avoidance of doubt:
  – writing 134.646 means 134.646 Hz

To see what is the MIDI note number of a key (in the standard equal temperament), you can just press it on your keyboard/controller and its number is displayed in the gray area “MIDI_IN_note”.

Fundamental Tones

From the Fundamental Mother you obtain the FUNDAMENTAL TONES (abbreviated are FTs).

All areas of the interface concerning the Fundamental Tones are blue.

Fundamental Tones are like a palette of tones. They are the blue area on the keyboard and when you press a Fundamental Tone key, all the HARMONIC TONES on the green keys are instantly recalculated.

The Fundamental Tones have two main settings:

• The TUNING SYSTEM, on which the FUNDAMENTAL-TONE SCALE is built.
• The CONTROLLER KEY-MAP.

FT Tuning System

The default setting

The default TUNING SYSTEM is the “equal temperament“, more specifically the 12-TET, better called 12-EDO, that means 12 equal divisions of the octave. We prefer the EDO suffix because it is more definite and intuitive.

The label here says:

n-EDx

That means:

n Equal-Divisions of the ratio x

For example, the classic equal temperament 12-EDO is obtained dividing the ratio/interval 2 by 12 logarithmically equal divisions. In other words, we divide the octave in 12 semitones. Here, n-EDx becomes 12-ED2 .

In the mathematics of music we say: twelfth root of two.

As I said, this is the default tuning system for the Fundamental Tone palette.

But it is possible to logarithmically divide another interval rather than the octave.

So, we might say: nth root of x.

This feature is very useful for microtonal or xenharmonic musicians. For example we can equally divide a higher fifth in 9 parts.

1. Click on “n-ED-x (Equal Temperament) if it’s not already selected.
2. Enter 3 (a fifth interval) in the “RATIO INTERVAL” grey text box and press enter.
3. Enter 9 (the divisions) in the “EQUAL DIVISIONS” grey text box and press enter.

You can see this log in the console:

FUNDAMENTAL TUNING: NEDX 3 9

Where n is 3 and x is 9.

Set x to 2 and n to 12 to restore the default tuning.

The other settings

With this column (that is a radio button set) you can change the Tuning System on which the FUNDAMENTAL-TONE SCALE is built.

• The first, n-EDx, is for Equal Temperaments as we have just seen.
• The second and the third are for using harmonics and sub-harmonics.
• The last four are not implemented yet (TODO!).
• The empty ones have no-function (I know… It sucks! 😛 ).

The HARMONIC and SUBHARMONIC tuning are more complex and they will be explained in an ad-hoc tutorial. They require a specific CONTROLLER KEY-MAP file (a file for the transposed tuning is in the keymaps/harmonic-subharmonic/ directory).

NOTE: Remember to check the console messages! If some features are not yet implemented you can read notices about it.

Controller Key-Map

Each step of the current FUNDAMENTAL TONE SCALE can be mapped to a controller key. The default controller keymap is contained in the CONTROLLER KEY-MAP file: as we can read on the GUI: ctrl1_fn.hcmap .

Obviously, different TUNING SYSTEMS provide different number of steps and require ad-hoc CONTROLLER KEY-MAPS. As I said, in the keymaps/harmonic-subharmonic/ directory there is a key-map for the HARM/SUBHARM TRANSPOSED tuning system.

The key-map file will be discussed in a section below.

Harmonic Tones

We have the green areas, that are about the HARMONIC TONES (abbreviated are HTs).

Also the HARMONIC TONES have two main settings.

• The TRANSPOSING TOOL, to change the pitch.
• Here again, the CONTROLLER KEY-MAP.

HT Transposing tool

In this little box, we can transpose the harmonic scale (the green keys) by octaves or entering a ratio.

• Clicking on “plus” you multiply by 2 (that is like go UP by an octave).
• Clicking on “minus” you divide by 2 (that is like go DOWN by an octave).

Entering directly the ratio, gives you the option to not be bound to the octave.

ALERT: transposed harmonics could be not in harmonic ratio with the Fundamental Tone!

Controller Key-Map

Such as the Fundamental Tones, also the Harmonic Tones are set/mapped into the CONTROLLER KEY-MAP file. This file will be discussed in the next section.

MIDI Map Files

In addition to the CONTROLLER KEY-MAP file there is another file: the INSTRUMENT BANK-MAP file.

Both of these files are simple data tables, in plain text format, with space or tab-separated values.

• The CONTROLLER KEY-MAP file is always required.
• The INSTRUMENT BANK-MAP file is required only if you are using the MIDI Output to retune a MIDI Instrument.

This two files are differently encoded and, for this reason, they have a different extension:

• The Controller Map is .hcmap
• The Instrument Map is .himap

The extension helps the user to better distinguish the files. Harmonync (PD) opens files of any extension, provided that they have been encoded in the right way.

If you are using the Built-in DSP only, you can completely ignore the INSTRUMENT BANK-MAP file and leave the default one.

Controller Key-Map File

So, let’s open the default CONTROLLER KEY-MAP file to understand how it works. It is under the keymaps/ directory. The file is “ctrl1_fn.hcmap“.

You can open and edit a key-map file with Notepad, TextEdit or any other text editor that saves in plain text format.

This file defines what keys you want to use on the controller. You can choose a set of keys from your controller and assign a function to each key. In this way you can build a Fundamental-Tone Scale and an Harmonic-Tone Scale.

We have three values each line, separated by a single space or tab. Each line is a key on the MIDI controller, with his functions: Fundamental or Harmonic. Value 128 stands for: No function.

• The first value means a key on the Controller (MIDI note number).
• The second value is the FT Number (“±32” is FT; “128” is NO FT).
• The third value is the HT number (“±64” is HT; “128” is NO HT).

41 -7 128
42 -6 128
43 -5 128
44 -4 128
45 -3 128
46 -2 128
47 -1 128
48 0 128
49 1 128
50 2 128
51 3 128
52 4 128
53 5 128
54 6 128
55 7 128
56 128 0
57 128 1
58 128 2
59 128 3
60 128 4
61 128 5
62 128 6
63 128 7
64 128 8
65 128 8
66 128 9
67 128 10
68 128 11
69 128 12
70 128 13
71 128 14
72 128 16
73 128 15

For example, here we have the MIDI note 55 (1st value = 55) that has a Fundamental function. In particular, the key 55 plays the FT number 7 (2nd value = 7). And no Harmonic function (3rd value = 128).

And we have the MIDI note 58 (1st value = 58) that has a Harmonic function. In particular, the key 58 has no Fundamental function (2nd value = 128) and it plays the HT number 2 (3rd value = 2), that is the second harmonic.

This map can be represented in this way:

Blue keys are FTs and green keys are HTs.

1st value

The first value is the MIDI note number of the key you chose to be used on the controller device.

The Harmonync assumes that you have an input MIDI controller. According to the MIDI specifications, a controller can send 128 different notes maximum per channel. They are numbered from 0 to 127. Your controller will use only a portion of these 128 keys. So, you have to choose a comfortable set of keys suitable to your needs.

To see the MIDI note number of a key, you can just press it and you have the number in the MIDI IN NOTE grey area (that’s why it’s so big).

2nd value

With the second value you can assign a Fundamental Tone function to the controller key.

The Fundamental Tone functions are expressed in values between -32 and +32, including zero.

It is very important to note that the root, that is the Fundamental Mother, is always the Function number ZERO.

If you are using the equal temperament 12-EDO, that divide the octave in twelve so-called “semitones”, these ±32 steps correspond to the semitones. As I previously said, this is the default tuning system for the FTs.

With the default settings, where FM is set to C3 and the FT tuning system is set to 12-EDO, we have:

• C3 is the function number zero (the root).
• C♯3 is the function number 1  (1 semitone above the root).
• B3 is the function number 11  (11 semitones above the root).
• B2 is the function number –1  (1 semitone below the root).
• G3 is the function number 7  (7 semitones above the root).
• G2 is the function number –5  (5 semitones below the root).
• C4 is function number 12  (12 semitones above the root).
• C2 is the function number –12  (12 semitones below the root).

If you don’t want to assign a Fundamental Tone function to that key, you have to set this second value to 128.

Key by key, you can build your Fundamental-Tone scale.

3rd value

Finally, with the third value you can assign a Harmonic Tone function to the key.

The Harmonic Tone functions are expressed in values between –64 and +64 including zero. Zero is actually used for a special feature, usable only with the Built-in DSP.

• Every POSITIVE number (1 to 64), is a Harmonic (also called Overtone).
• Every NEGATIVE number (–1 to –64) is a Sub-Harmonic (also called Undertone).

This Harmonics and Sub-Harmonics, are the whole multiple or fraction, of the last pressed Fundamental Tone.

• Number 1 is the first harmonic and corresponds exactly to the FT because it is multiplied by 1.
• Number 2 is the second harmonic and stands for the frequency of the FT multiplied by 2.
• Number 7 is the seventh overtone.

And so on…

• Number –1 is the first sub-harmonic and corresponds exactly to the FT because it is divided by 1.
• Number –3 is the third sub-harmonic, that is the frequency of the FT divided by 3.
• Number –6 is the sixth undertone.

And so on…

The numbering system of Harmonic Tones is more intuitive. It corresponds to the canonical harmonic or overtone naming.

If you don’t want to assign a Harmonic Tones function to that key, you have to set this third value to 128.

Strange default key-map?!

Maybe, you’ve noticed that the Harmonic Tones have a strange order on the default key-map: the keys 64 and 65 have the same function (the 8th harmonic) and the keys 72 and 73 are inverted (key 72 is the 16th harmonic and key 73 is the 15th harmonic).

Why this strange map?

Because using a piano keyboard, I’d rather have the even harmonics on the white keys and the odd harmonics on the black keys. But to do this, we need a logarithmic keyboard like this:

The classic piano keyboard, with a pattern that repeats every twelve keys, is not the best solution for playing harmonics. So, the default key-map is my personal solution to divide even and odd harmonics respectively in white and black keys using a piano keyboard.

Also the Fundamental Tone mapping might seem strange: starting from zero, there are just seven keys above and seven below zero. With the default classic equal temperament it means a maximum range of an ascending fifth and a descending fifth from the root (or zero). Why?

This because, when I started this project I needed just a fifth upon and a fifth under the root  😉 .

There is an alternative key-map in the keymaps/ directory. The file is “ctrl2_fn.hcmap“. Other maps will be uploaded soon. In the meantime… if you don’t like the default key-map, you can edit it or create your own.

2nd and 3rd value

You must be wondering: why two values to assign a key function?

Because, in theory, you might want to assign a fundamental tone and a harmonic tone to the same key. So, pressing that key, the Harmonync would produce a fundamental and a harmonic tone at the same time.

I’ve never used this possibility and I never checked its proper implementation. Probably, at this stage of development it can result in undesirable effects. I recommend: do not use this possibility yet.

So, to avoid mistakes:

• The FT keys must have the second value (the fundamental function) set to 128.
• The HT keys must have the third value (the harmonic function) set to 128.

To summarize

• The CONTROLLER KEY-MAP has one line for each used key on the controller.
• Each line has three values: the controller note number, the fundamental function number and the harmonic function number.
• The Fundamental Tone number ZERO is always the Fundamental Mother.
• Value 128 stands for: No Function.
• You can edit or create your own key-map file with a notepad, in plain text format.

Loading a Controller Key-Map

Click on the red button “LOAD CONTROLLER MAP” to open a file-browser window and load a new controller key-map.

The current CONTROLLER KEY-MAP file is written in red. The default one is: ctrl1_fn.hcmap . It is in the “keymaps” directory. There you have an alternative key-map file: /keymaps/ctrl2_fn.hcmap .

Create your own Controller Key-Map

Let’s see how you can create your own key-map. In particular, we are going to re-create the other map you can find in /keymap directory: the file ctrl2_fn.hcmap

Create a keymap is very simple.

First step. Imagine the layout you want to create.

For example, I want two octaves of FT and the first 16 HT. Possibly maintaining the even harmonics on the white keys and the odd harmonics on the black keys. All this should be mapped to a range of 49 keys (or 4 octaves).

An example of this layout is the following:

In the keymap/tools/ directory there is an Excel file, useful to conceive and create a controller keymap. The file is harmonync-keymapping-tool.xlsx . You can find the previous layout in the “layout-maps” worksheet.

Second step. Decide the MIDI key range you want to map your layout to.

For example, in order to use the default key range of my keyboard, I choose the MIDI notes from number 36 to number 81.

You can see the resulting layout:

Note that in this map:

• The FTs are from –12 to +12. They are mapped from the MIDI note number 36 to number 60.
• The HTs are from 1 to 16. They are mapped from the MIDI note number 64 to number 81.
• The MIDI NOTE NUMBER 61, 62 and 63 are unused.
• The 8th and the 12th harmonic are mapped twice. This is a personal choice in order to maintain the odd harmonics on the black keys.

Third step. Compile the map.

In order to avoid mistakes, you can use the mapping tool in the Excel file.

Switch to the “MAPPER” worksheet. This sheet is protected to avoiding mistakes. You can edit only the second and the third column. However, the sheet is not password protected.

There are seven columns with data. For now, let’s see the first four columns.

1. The first column (A) is the MIDI note number, from 0 to 127. It is locked.
2. The second (B) is the Fundamental Tone. Here you can enter a number between –32 and +32. 128 is no-function.
3. The third column (C) is the Harmonic Tone. Here you can enter a number between –64 and +64. 128 is no-function.
4. In the fourth column (G) you have a useful debugging notices area. It is locked.

* Note that there are some hidden columns.

Fourth step. Copy just the first three columns of the used rows, in this case from 36 to 81, and paste them in a plain text editor.

Remove the unused lines 61, 62 and 63. As you can see, now it jumps from 60 to 64:

To be sure the file is in plain text, save in TXT format and then rename the extension from .txt to .hcmap .

You can load the new file as we see before.

Instrument Bank-Map

Harmonync needs also a map of the Instrument in order to play it via MIDI.

The INSTRUMENT BANK-MAP file is used only to send the MIDI OUTPUT. If you are using the Built-in DSP only, you can completely ignore the INSTRUMENT BANK-MAP file and leave the default one. Instead, in order to send out via MIDI the key/tones you set in the CONTROLLER KEY-MAP, you need to map them on the INSTRUMENT BANK-MAP file.

The INSTRUMENT BANK-MAP a sort of virtual representation of the Instrument’s keyboard. A key must be mapped on this file in order to be sent out via MIDI.

Although (in theory) it would not be necessary when you are using the Pitch-Bend Tuning Method, the INSTRUMENT BANK-MAP file is required anyway. It could be useful to implement new features.

By using the MTS System Exclusive tuning method, the INSTRUMENT BANK-MAP represents the tuning bank that must be sent to the Instrument. So, in this file you can describe the position of every single tone on an MTS compliant instrument. In this tutorial, we don’t use that method. An ad-hoc guide is planned.

As I said, also if you are using the Pitch-Bend Tuning Method you have to set the INSTRUMENT BANK-MAP file.

Values

This file is similar to the CONTROLLER KEY-MAP but with a different encoding. The main difference is that, on the instrument, a key cannot have two functions. A key can be a Fundamental Tone or (NAND) a Harmonic Tone, not both. For this reason the encoding of the values inside this file is different from the CONTROLLER KEY-MAP one.

Let’s open the default INSTRUMENT BANK-MAP file, to understand how it works. It is under the keymaps/ directory. The file is “inst1_fn.himap“. Such as the CONTROLLER KEY-MAP file, you can open and edit it with Notepad, TextEdit, or any other text editor that saves in plain text format.

So, the CONTROLLER KEY-MAP file defines which tones/keys you want to use on the Instrument. If the Instrument is MTS compliant, this file defines also the position of every single tone/key on the Instrument’s keyboard.

We have three values each line, separated by a single space or tab.

• The first value means a key on the MIDI Instrument (MIDI note number).
• The second value gives the meaning of the third value (“0” zero is FT; “1” is HT).
• The third values can be the FT Number or the HT Number (it depends on the second value).

41 0 -7
42 0 -6
43 0 -5
44 0 -4
45 0 -3
46 0 -2
47 0 -1
48 0 0
49 0 1
50 0 2
51 0 3
52 0 4
53 0 5
54 0 6
55 0 7
56 1 0
57 1 1
58 1 2
59 1 3
60 1 4
61 1 5
62 1 6
63 1 7
64 1 8
66 1 9
67 1 10
68 1 11
69 1 12
70 1 13
71 1 14
72 1 16
73 1 15

For example, here we have the MIDI note 55 (1st value = 55), that is assigned to a Fundamental function (2nd value = 0). In particular, the key 55 plays the FT number 7 (3rd value = 7).

And we have the MIDI note 58 (1st value = 58), that is assigned to a Harmonic function (2nd value = 0). In particular, the key 58 plays the HT number 2 (3rd value = 2).

Generate a Standard Instrument Bank-Map

Compiling the INSTRUMENT BANK-MAP file is pretty simple. The Excel file harmonync-keymapping-tool.xlsx located in the keymap/tools/ directory generates automatically an INSTRUMENT BANK-MAP from the CONTROLLER KEY-MAP.

The INSTRUMENT BANK-MAP automatically generated by the worksheet is called “Standard“. This Standard Map has the same key-range and structure as the CONTROLLER KEY-MAP.

Only if you are using the MTS Tuning Method you could need a “Custom” INSTRUMENT BANK-MAP file. If you don’t use the MTS Tuning Method while playing the Instrument’s keyboard directly, you don’t need a Custom Map.

To simplify, an INSTRUMENT BANK-MAP can be:

• Standard: the same key-range and structure as the CONTROLLER KEY-MAP.
• Custom: place each key in the position you need in order to play the keyboard of a MTS compliant Instrument.

For avoidance of doubt: a Custom Map is useful only if you want to map the keys of the keyboard of a MTS compliant Instrument differently than the CONTROLLER KEY-MAP.

Since probably nobody will need a custom map because MTS hardware tools are virtually non-existent, I will not explain the INSTRUMENT BANK-MAP file. I recommend you to automatically generate it with the Excel tool.

Let’s resume the previous example. We have been created the ctrl2_fn.hcmap CONTROLLER KEY-MAP file. Now we need an inst2_fn.hcmap INSTRUMENT BANK-MAP file in order to send a MIDI Output.

Open the harmonync-keymapping-tool.xlsx spreadsheet. In the MAPPER sheet we have seven columns with data. We have seen the first four columns in the previous section. Now, let’s see the last three ones.

When you compile a CONTROLLER KEY-MAP entering values into the 2nd (B) and 3rd (C) column, the cells in the 7th (J) and the 8th (K) column are compiled automatically.

Now, copy just the last three columns of the used rows (in this case from 36 to 81) and paste them in a plain text editor.

Remove the unused lines 61, 62 and 63. As you can see, now it jumps from 60 to 64:

To be sure the file is in plain text, save in TXT format and then rename the extension from .txt to .himap .

You can load the new file as we see before.

 

Now you can go to the next section: The Output.

 

This content has been updated on June 10, 2016 at 7:26 pm