Velocity keyswitches retuning

This script is based on a totally unofficial spec. for retuning instruments via midi, developed by a group of microtonalists in the Xenharmonic Alliance facebook group. I wrote it to try out our ideas for Kontakt instruments. BETA SOFTWARE - WORK IN PROGRESS - comments invited.

I have more features planned for this script in the future, as well as wishes that may be implemented see also Velocity keyswitches retuning script wish list

We developed it as an alternative to the official midi tuning sysexes. Nowadays sysexes can't be used at all in many environments. For instance there is no way to access them in a Kontakt script. Ideally we want a spec that let's instrument designers and synth programmers add real time tuning table support in any environment, or the widest range of possible environments. For more about the motivation, see Original Spec page - Tuning RPNs (specification draft).

Do you just want to get the script and add it to your Kontakt instrument? If so, skip to.

To find out more about the example scales see The scales in the velocity keyswitches retuning Kontakt script.

For programmers who want to add the capability to your instrument, see. Or if you want to add the capability to some other environment not Kontakt, see

Introduction
What this script does:
 * lets you set up a tuning table on a Kontakt instrument via midi using "velocity keyswitches". It sends a rapid sequence of notes 126 and 127, with the tuning instructions and data coded into the note velocities. These notes are well above the normal playing range of most midi instruments.
 * Individual midi notes in the tuning table can be tuned to any pitch in the midi note range.
 * Velocity keyswitch retuning is switched on by sending the undefined controller 119 with data 119. It is switched off by sending midi note 127 with velocity 100.

This script can be added to many instruments in other formats so long as you convert them to the Kontakt format first.


 * Most sound fonts and .gig files can be imported directly into Kontakt.
 * Many other sample based instruments can be converted to Kontakt format e.g. using Chicken Systems universal translator - except of course for encrypted or locked instruments (e.g. the libraries of the Aria player are encrypted and can't be imported).
 * You can add the script to any of these instruments

You do need the paid for Kontakt rather than the free Kontakt player or the Kontakt demo to add a script to a Kontakt instrument.

This script works with many Kontakt instruments, but not all. Sometimes you need to disable existing scripts, and sometimes there are no free slots to use. For more about this see

What it looks like
Here is what it looks like when you make it into the performance view of a Kontakt instrument. This is the Maestro Concert Grand instrument, a .gig file originally which I imported into Kontakt and then added the script to it.



You can now play it in any tuning you like, with many examples included in the scales droplist, and others can be sent to the instrument via midi using velocity keyswitches.

If you add the script to an existing Kontakt instrument with a performance view already set up, then you will see the same thing, but in one of the script tabs for the instrument.

Example sounds to show the flexibility of tuning tables with real time per note updates
To give some idea of its flexibility, here are some examples of what you can achieve in software sending velocity keyswitches to various Kontatk instruments with this script added to them.

A harpsichord as you've probably never heard it before: 50 note harpsichord glide

This has around 50 or so notes - all gliding at different speeds and some in different directions all at once, all in the same channel. The method allows an individual note to be retuned without need to resend the whole table each time.

More examples: Two choir voices gliding in opposite directions, Grand Piano multi pitch glide, Viola, Bassooons

Simpler sound examples with fixed tuning
Here are some simpler ones just going up a scale in 120 equal: Choir "mms" on alto,

Celesta -you can hear how it uses a different sample as it crosses note boundaries. Should be every 100 cents so every 10 steps of 120-et Celesta

This time with the notes sustained, and using a harmonic series: harmonic series on 'cello, and at tenth speed: harmonic series on 'cello, tenth speed

These were all done by sending velocity keyswitches to a single Kontakt instrument in a single channel. I used a beta of Bounce Metronome to do these tests, will be available in the next release of the software.

You can also try the test midi files. Available here: Midi tests for velocity tuning keyswitchss. To try it out, first you add the script to a Kontakt instrument as described below then you can open one of the example midi files into your DAW and render it or play it. It needs the full Kontakt to be able to edit the instruments and to add the script.

Other elements of the user interface
This script also:


 * adds a series of knobs and other controls which give feedback about the tuning of the note as you play notes, and you can also use these to adjust the tuning of any of the notes of your instrument by hand.
 * adds a short list of example scales which you can access in the user interface including n equal scales with any number of notes per octave.

This is the minimal version, just three lines of controls:



Those controls are visible when you switch to the script editor. You can also make them the "performance view" in which case they appear on the front panel of the instrument as in the screen shot.

You can show it in different ways using the drop menu at top right, which also gives you access to a "tweaks" screen and documentation - short summary of the velocity tuning + gives url of this page.

Here is a version with knobs to adjust tuning of the notes and to give quick visual feedback of the tuning as you play:



The menu here has a droplist of example scales to get you started right away



Also a short list of scales you can put on the black keys



Just to try out one way of many ways of using a keyboard microtonally with one scale on white keys another on black.

This is the tweaks page - most important thing there is the instrument range which you might need to set for instruments with keyswitches, otherwise the script could retune notes into keyswitch notes.



The ratio recognition sensitivity defaults to 0.001 so it only shows as a ratio if it is accurate to the nearest millicent. It also shows it as a ratio if the retuning program sends a velocity keyswitch message to set the ratio value for the note, if so just displays it exactly as received.

Sometimes it may be useful to set the sensitivity higher, so that as you play notes, you can see what the nearest ratio is - in the example here I've set it to 14 cents. This only makes a difference to the Ratio field in the user interface, and is visual only, makes no difference to the tuning of the note.

This is the documentation screen



How you can use this script
One way you can use this script is to insert these keyswitches into a score, just like the low numbered keyswitches used to change instrument articulation. The notes 126 and 127 are high enough so they are never needed in a normal score, well above the pitch range of a piano.

These instructions can also be sent to the instrument via midi in real time by retuning software - I have added the capability to the beta of Bounce Metronome labelled as an "experimental feature" for now, so will be ready for the next release and we expect other tuning software such as SCALA, and Alt Tuner (and my own Tune Smithy) to support this idea in the future (or some version of it as the spec is still under discussion).

The instructions could also be sent on a "per key" basis for microtonal keyboards. If the keys are dynamically retuned, then the limitation to 126 (or 128) notes per channel is only a limitation on the number of notes you can play simultaneously in a chord.

This could permit "monster keyboards" with hundreds of notes all playing midi notes in any desired tuning of the keys, on a single midi channel. See

This script works for almost any instrument which can be played in Kontakt. Many other sample based instruments can be converted to Kontakt format - and are often available in it already - this means it can also be used for most sample based instruments. That includes all instruments in unencrypted soundfont format (sf2) and in the .gig file format - this script can be used with any of those instruments.

Some sample based instruments however such as Garritan Personal Orchestra and Vienna Symphonic Library are not available as Kontakt instruments. That just means that this script can't be used with them, but there may be other ways to add this capability, either to respond to velocity tuning keyswitches, or other methods. The same applies for VSTi and software or hardware synthesizers.

Contributors
For the draft of the spec see Tuning RPNs (specification draft).

The main contributors were myself (Robert Walker), Kite Giedraitis, Rob Fielding, and Graham Breed, and Ozan Yarman came up with the idea of using high numbered keyswitches.

It's been through various stages. The original spec used undefined RPNs for retuning, and undefined controllers were also explored.

This script uses high numbered velocity keyswitches, because I couldn't get the tuning RPNs or controllers methods to work in Kontakt. This may be a good solution for other environments as well. Sysexes can't be used so the MTS sysexes are not an option in this particular environment. Comments on all this by synth authors and developers are welcome!

I developed a script for Kontakt instruments to explore our ideas. I tried various methods but only the velocity tuning keyswitches worked with Kontakt, at least on my computer. The other ideas using controllers and RPNs are included in the beta script for comment and experimentation.

License
Copyright (c) 2013 Robert Walker

This software is provided as-is, without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not   claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution.

This is the ZLib license suitable for free software and also for open source software and commercial use https://en.wikipedia.org/wiki/Zlib_License

This script will only work in Kontakt, not in VSL, GPO, etc
This script will only work in Kontakt. Other sample players won't understand it, and it is impossible to do the same thing via midi instructions or VSTi plugins or effects. VSTi for instance would need to be reprogrammed to understand these instructions.

This script won't work for instruments that are commercially encrypted and use their own sound engine such as Garritan Personal Orchestra or Vienna Symphonic Library. (It will work with the VSL instruments included in Kontakt).

The sound engines for these other instruments would need to have extra programming to respond to these high numbered velocity keyswitches.

Similarly this script can't be used for VSTi or other synths. Other methods would need to be explored to add this capability in other environments.

Why Kontakt only?
It needs the Kontakt scripting engine to work. AFAIK no other program can interpret this language. So this script will only work in Kontakt.

The script adds a tuning table to the instrument, and then changes the way the instrument responds to midi messages so that the velocity keyswitches can alter the pitches in the table.

It is not possible to do any of this with a conventional midi plug in, as it has no access to any internal tuning tables in the instrument.

Programmers in other environments would have to write their own code to do this.

For more about this see Why Kontakt only?

Why doesn't this script use the standard Tuning sysexes?
It can't use the standard tuning sysexes because there is no support for sysexes in the Kontakt scripting language.

Early ideas - controllers and RPNs
Our first idea was to use RPNs. See the Tuning RPNs (specification draft) for details. However I ran into issues implementing it as a Kontakt script. It only got about 12 of the RPN instructions out of a batch of 512.

Another idea was to use controllers. This idea seemed promising at first. But I ran into the same issue. If you send hundreds of controller messages, all for the same four controllers, in a short period of time, the script only gets notification of the last value of each of the controllers. That is understandable if you think of the controller messages as updating the value so the script only needs to know the latest value of the controller at any one time.

It was possible to get the controllers to work, but only if my program sent them at intervals of about 10 ms between each message, or about 40 ms between each occurrence of the same controller. Send them any more quickly than that and some got lost.

So, I was completely at a loss about how to proceed. This may just be a Kontakt issue, but it seems to me it might also be an issue with other synths as well. With controllers then generally your program wants to know the current value at any time and is less interested in the sequence of messages that lead to that value, so it is at least reasonable for a host or engine to discard controller messages if there is too much traffic.

The high numbered velocity keyswitches idea
This is the brilliant suggestion of Dr. Ozan Yarman of Başkent University. The topmost notes of the midi range are rarely used in instruments - are well beyond the top notes of a piano. Notes also are high priority so less likely to be dropped than controllers. It turns out that we only need to use notes 126 and 127 (after several revisions of the idea).

Keyswitches are often used to change playing styles of instruments, but typically they use notes below the natural range of the instrument. The high notes are normally not used for anything.

Note 127 is used to send "instructions" so 127 with velocity 4 sends the instruction "retune a single note with the next 4 data bytes". This is a similar idea to the midi "status bytes".

Then 126 is used for "data" with the velocities set to the data values.

So we get four 7 bit bytes to retune a note to anywhere in the midi pitch range:

There is a minor issue here. You can't send a zero value as a velocity (because it is treated as a note off). To deal with that, the instruction 127,127 is treated as data value 0.

The pitch bend here is an offset from the output note in the range -50 cents to 50 cents. (Always the same range -50 to 50 cents no matter what range you have for normal midi pitch bends). This gives the maximum of pitch accuracy and eliminates any problems due to unknown pitch bend range, or midi instruments with different hard coded pitch bend ranges.

For more about this see and

We can also achieve a full 128 notes retuning. You need to send an undefined controller 119 with data 119 to switch on velocity tuning. After you have completed updating the tuning table with velocity tuning keyswitches, you can send the instruction 127, 100 "End tuning" which switches off velocity tuning until the next 119, 119. Like this:

For details see

Sketch of how it works
This script monitors controllers and notes. When velocity tuning is switched on, it records all the note on velocities for notes 126 and 127, and uses information encoded into these velocities to build a tuning table in the internal memory of the instrument.

When you play an ordinary midi note, it looks it up in the table. It then tells the instrument to play the desired output note instead (using the sample for the desired output note). It then adjusts its tuning further by up to 50 cents up or down, depending on the information in the table for that input note.

How to add this script to a Kontakt instrument
Note, this is a BETA script - particularly since the spec itself is work in progress.

You need the full version of Kontakt to install this script. You can't use this with the free Kontakt Player as it doesn't have script editing capabilities (except briefly in demo mode). I tested the script in Kontakt 5 but only use features in the Kontakt 4.2 reference manual, so it should be backwards compatible with Kontakt 4.2.

Authors of instruments for Kontakt will also be able to add this script to their instruments. The license permits it to be used in this way, in any project, free or commercial.

You can get the script here: kontakt_high_keyswitches_tuning_no_release_retuning.txt

Here it is again, with syntax colouring for programmers: Kontakt retuning script

To add this script to a Kontakt instrument:


 * 1) click on the wrench icon
 * 2) then on Script Editor,
 * 3) then look for an empty slot labelled Click on tab to select it and
 * 4) then click Edit.
 * 5) Then copy and paste my script into the edit field. You may need to use Apply From Clipboard to achieve this.
 * 6) Then click Apply (button to far right)

The title of the script gets filled in automatically, the button and knobs will appear, and your instrument can now be micro-tuned in Kontakt.



You will be able to retune the input notes straight away using the knobs. The tuning is persistent, so you can edit the tuning by hand and save the tuning, and it will remain tuned like that next time you use the instrument.

How to use the controls to retune individual notes by hand
This script adds various controls to the user interface for your instrument.

To retune any note on the keyboard to anywhere in the midi range, you


 * 1) Use the "Note" knob to select the note you want to retune
 * 2) Use the "To" knob to select the note to retune it to.
 * 3) Set the amount of the cents bend with the Cents, Centicent and Last digit knobs
 * 4) Alternatively, double click on the text field below the Cents knob and enter the amount of the bend as text.

How to retune the instrument via midi
You can also insert the necessary velocity keyswitches into a score by hand and then play them via midi to retune the instrument.

The next update of Bounce Metronome when ready will be able to send high numbered keyswitches to retune these instruments via midi, so e.g. you just need to select a SCALA scale from a drop list to retune all the notes to that scale.

Some other programmers of retuning software will probably do the same.

NOTE - BETA, WORK IN PROGRESS

Test midi files
This test file retunes all 128 notes of the instrument to 120-et using the velocity tuning keyswitches 126 and 127.

It then plays a 128 note glissando in 120-et. Added an example .wav recording so you can hear what it sounds like.

120-et-complete-with-128-note-glissando.mid (wav)

It retunes all 128 notes, adds a pause of 50 ms before switching off the velocity retuning method, and then plays the notes with a glissando up and then down.

Here it is without any notes played, just updates the tuning: 120-et-complete.mid

This version retunes the notes 0 to 125 - and so doesn't need any pause afterwards.

120-et-to-125-glissando.mid (wav)

Here it is without any notes played, just updates the tuning: 120-et-to-125.mid

Both of them also have velocity keyswitches to update the tuning description as well.

For more midi tests see Midi tests for velocity tuning keyswitchss. Most of those play notes and you can use them to test that the script is working.

Apart from that is best to use software to make midi files as then you can make midi tuning files for any tuning you desire. This will be possible in next release of Bounce Metronome in the next few days. It will be a free feature if you just want to export these retuning midi files, or play in the tuning in real time from pc keyboard (I'll make it a paid feature if you need to relay in real time from Midi in, e.g. because you want to use some of the other features of Bounce Metronome such as tonic switching using an octave of the keyboard, also makes it a bit quicker to change tuning as you play).

Trouble shooting the script install
Many instruments can be retuned with the notable exception of most of the Kontakt pianos. For more about this see How to unlock Kontakt pitch bending

Disable all other scripts
If it doesn't work, the first thing to do is to disable all the other scripts. This usually fixes it. Then enable the scripts one at a time until you find the one that interferes.

The script that causes most issues here for the Kontakt Factory instruments is the first Options tab, with the drop menu of tunings.

If there are enough free slots, you might find you can copy / paste those problematical scripts into a later slot than the one used for this script.

Install in first script tab if possible
If it still doesn't work, and the first tab is free or you can move the other scripts, install it in the first tab. to prevent interference with other scripts.

Merge with another script
If the script slots are not protected, or you are the original designer of the instrument, you might be able to merge my script with the script already there. This is not hard to do, it needs minimal knowledge of how the scripts work.

The script is designed to be easy to merge with other scripts. All variables and routines start vksr_ or kspML_ so chance of variable collision is low, and if you do happen to have variables or routines starting with those letters, it is easy to fix that by doing a search and replace of the script first before the merge.

Simply copy the "on init" section to the "on init" handler in the existing scripts, and then add all the routines to the end of the script. If the script has "on note", "on release", "on controller" handlers then you need to merge those handlers with the script - copy the relevant code into those handlers.

The minimum you need to add is the script in the previous section,. This will permit velocity retuning via midi and adds a 12 equal reset button, but no other user interface controls. It should also be easy to add the entire script.

Note the beta script has some extra code to handle "rpn retuning" and "controller retuning" as well as the old velocity key switches retuning method - this code is just there for beta testing; it can be removed. The final release will probably omit it, depending how the discussion of the spec goes.

Free script slot issues
Some instruments have no free slots for new scripts. Many of the Kontakt pianos are like this for instance. Often the slots are locked or password protected. If so, AFAIK, the only way to use this script is to contact the original author of the instrument and see if they can modify it to include this script.

Out of tune release sample issue
Most instruments work just fine with the default script. However, you might find that the note changes pitch at the note off, when it triggers the "release sample". This happened a few times during beta testing but I think it might be fixed now.

If that happens follow the instructions in the script, which disables the old release sample, and triggers its own new release sample, tuned to match the output note + pitch bend:

It is the same script as before, just adds three lines of code including $retune_release:=1 which switches on a block of code later in the program.

It is a bit of a kludge because the only way you can retune these release samples in Kontakt is to DISABLE ALL AUTOMATIC RELEASE SAMPLES and retrigger a new release in the script when you get notification that the note needs to be released.

Luckily most instruments don't need this tweak. It was needed in an earlier version of the script but so far haven't yet found a situation where it is needed now. If you do need it, it might work fine, but is not guaranteed to work.

Instruments that can't be scripted in this way - Kontakt pianos
Most of the factory preset instruments work fine. Sometimes you need to bypass the Options script tab to get them to work.

The main problem is with the Kontakt pianos. Most of these have no free slot. (The harpsichord and organs are fine).

If there are no free slots, your only options are, to see if the manufacturer of the instrument can do anything about it, or to look for an alternative instrument.

In the case of the Kontakt pianos, the August Foerster Grand has two free script slots, and this one is retunable using the velocity tuning script, so long as you bypass the Options script tab and add my Velocity retuning script to one of the two remaining free slots.



Perhaps the other Kontakt pianos could be retuned some time in the future if Kontakt themselves choose to add my velocity retuning script to them, either merge with one of the existing slots. They could probably retuned, also, if Kontakt find a way to add extra script slots to their instruments.

You can also use the Maestro Concert Grand which is in .gig format and easily imported into Kontakt.



Here I've made the velocity retuning script into the performance view.

Useful links to download free Kontakt instruments
These instruments work with the full version of Kontakt. Most of them can be microtuned using this script with a simple copy / paste of the script into one of the free script slots in the instrument as in the screenshot above.

http://rekkerd.org/freebies-for-native-instruments-kontakt/

Help for developers who want to add this capability to Kontakt instruments
The easiest method is to simply add it as a new script tab. This is likely to work best if you put it into the first tab, and if your script uses keyswitches, be sure to set the instrument range, so that it can't retune any notes into keyswitches.

However, you may have all the script tabs already taken, if so you need to merge it with an existing script.

See the instructions at the head of the script to merge it with an existing script. All variables and routines start vksr_ or kspML_ so chance of variable collision is low. If it does happen, is also easy to fix, do a search and replace of the script and replace these prefixes with one that doesn't collide before you do the merge.

For the ui, you could use the "Tuning only" just add a statement:

which gives just three lines of controls



You might also want to shift the whole ui down e.g. to shift it down by two lines

You can of course modify it further by changing the move_control statements. These are located at the end of the init.

You will probably want to remove the menu of different pages such as tweaks, documentation, version with knobs etc, to do that add

to the end of the "on init" section.

Note, as it is a beta script it currently also adds capability to retune using undefined controllers, and RPNs and an older velocity tuning method. These will probably be removed eventually. They make no difference to the rest of the script, and do not appear in the user interface, are only selectable by sending the controller 119 with various values.

Minimal script for programmers
This is a minimal version of the script which may be useful if you want to write your own script to do velocity retuning from scratch, or you just want to add the capability to retune via midi in without the "per note" tuning controls and visual feedback, or the menus or example scales.

It removes all the user controls except the "reset to 12-et" button. It removes all diagnostics and it removes all the retuning methods except for the keyswitches using notes 126 and 127, and removes the release sample retuning (not normally necessary as most instruments tune them correctly when you change the tuning of the note).

The result is less than 300 lines of code.

This is easier to read, so may be useful for programmers who want to see how it works.

SORRY THIS NEXT VERSION IS BUGGY, MADE A MISTAKE WITH UPLOADED FILE. WILL FIX IT SOON. TRY VERSION WITH DIAGNOSTICS INSTEAD.

kontakt_high_keyswitches_tuning_minimal.txt or with syntax colouring kontakt_high_keyswitches_tuning_minimal.htm

As you see, then most of the work is done in the function process_tuning_keyswitches plus a small amount of code needs to be added to on note and on release, some variables need to be added to on init and you probably will want to add a "reset to 12-et" ui control, the script handles this in on ui_controle ($ResetTo12EQ)

Here is a the minimal version with diagnostics, useful if you need to debug the script, but the extra diagnostics lines make it a bit less easy to read. kontakt_high_keyswitches_tuning_minimal_with_diagnostics.txt or with syntax colouring kontakt_high_keyswitches_tuning_minimal_with_diagnostics.htm

Help for developers who want to add this capability to other programs
The Kontakt might be useful for you too:  kontakt_high_keyswitches_tuning_minimal.htm

The script is about 300 lines. It shows how to receive velocity tuning keyswitches in a midi synth. If you need help reading it, see - several things about the language are unusual such as # for !=.

I plan to provide example c-code for both directions, to send and to receive velocity keyswitches, once the spec is fully agreed on and stabilized.

This method can map any note to any pitch
It doesn't matter that 126 and 127 are used as tuning instructions and data. You can set up the tuning table to map any notes to any notes in the entire midi note range using the appropriate instructions.

Usually note 127 is too high in pitch to be of any interest, but you do get other "unorthodox" ways of using the midi range such as repeats of the same instrument with different articulations etc. If so, no worries, you can set any note you like to play midi note 127, e.g. you could set note 60 to play 127.

Undefined controller 119 to switch on and switch between retuning methods
There, tuning software would send 119, 0 to switch off tuning, but synth would switch it off in response to any unrecognized value.

Synth can default to not retunable and require CC 119,119 (or vals 120 or 121) to switch it on.

Advantages:

Helps prevent accidental retuning
To retune the synth you have to


 * send the undefined controller 119
 * send it with a value of 119-121
 * send a recognised note 127 status byte
 * immediately follow it by note 126, or another 127 with velocity 127

This is also why I chose 119 here for the value. It is easy to remember, send avalue same as the controller number. Also isn't a normal value for an on / off controller such as 0, 64, or 127

Some hardware keyboards are preset to send undefined controller values for some reason. So there is probably nothing we can do to logically prevent accidentally retuning. But this way it is at least highly unlikely to happen. 119 seems an unlikely undefined controller for a keyboard to be preset to send automatically, as it is the highest numbered undefined controller.

Does anyone reading this know of any hardware keyboard which is preset to send undefined controller 119 when you adjust one of its controls?

Lets you retune and use all 128 notes for the velocity tuning keyswitches
Example, with the 126, 127 velocity tuning keyswitches, this retunes the input note 127 so that it plays middle C

Now because the velocity retuning is switched off we can play midi note 127 on our array keyboard, and it will play a middle C, and not change the tuning of the synth.

Delay needed before switch off retuning for 128 notes retuning - bug?
Note though that in my tests with Kontakt, for some reason a gap of about 50 ms minimum was needed between the original 119,119 and the final 119,0, otherwise the script never receives the 119, 119.

I tested this by sending just two messages to Kontakt, 119, 119 and 119,0, the script never gets notificaton of the 119 119. If you put note ons between the two messages, the script is told that the controller value of 119 for those notes is 0. If you have a delay of 50 ms between the 119, 119 and 119,0 then everything works fine. The same thing also happens in VST Host and Cantabile, the two hosts I've tested so far.

Suggests there must be some pre-filtering of controller messages somewhere along the way. Anyone got any ideas about this?

Tuning velocity keyswitches with just two note numbers 126 and 127
To switch on this tuning method you use

Then the idea is, to treat the note velocity for midi note 127 for instructions, as a kind of "status byte" and the velocities for note 126 as the "data bytes"

Like this:

This should be followed by

(behaviour is undefined if this protocol is not followed)

Zero data handling then become easier

Could have running status for our new "status bytes", so if you want to send a series of pitch adjustments, you don't need to keep resending the "status byte", like this:

That's 12 bytes total per note retuned, or using normal running status for the note ons, 4 for "header" + 8 bytes per note.. Or, if you make sure to switch the notes off, 24 bytes, and with normal running status, 4 or "header" + 16 bytes.per note

With note offs as note on 0, is

If one of the values is 0, e.g. f is 0 you just send a 127,127 for that data byte.

"End tuning" and disable velocity tuning
Any unsupported instruction will stop the "running status". But we also need the capability to switch off velocity tuning after full 128 note tuning tables.

You then need to send the undefined controller 119, 119 to switch the velocity tuning back on again.

You could alternatively just send the undefined controller 119 with value 0 to disable velocity tuning, but there is a quirk in Kontakt that the effect of a controller change can get "pre-dated" to notes received before the controller (perhaps due to audio buffering?) The result is that the last few notes in the tuning table may fail to be updated if you do it that way. See

If you use 127, 100 to disable velocity tuning then there are no such timing and sequencing issue. Though the value for the undefined controller 119 doesn't change, this doesn't matter, the 127,100 can still disable velocity tuning until next receipt of a cc 119, 119 message. I.e. it's the receipt of a cc 119, 119 that switches on controller retuning.

Pitch bend format
The pitch bend follows the same format as a standard midi pitch bend, except that the pitch bend range (just for these messages) is hard coded to +- 50 cents (for maximum sensitivity). So there are 16384 steps for the range -50 to 50, giving a pitch bend resolution of 0.0061 cents.

That is good enough for even the most demanding of microtonalists in almost all situations. In theory, you could notice a difference in tuning of less than a hundredth of a cent on a super accurately pitched instrument if you had polyrhythmic beating partials beating at different rates from each other but this situation is likely to be exceedingly rare. If you need to set the pitch to greater accuracy, you can do this too with this script as it adds an extra fine pitch bend feature see (optional instruction).

How to work out the data to send from the pitch bend in cents
Formula is: pitch bend = 128*coarse + fine.

As usual(64*128) = 8192 is the zero position. The range is +- 0.5 semitones. So there are (8192*2) steps to a whole tone.

So to get the pitch bend from the bend in cents use:

pitch bend = (bend in cents/100) * (8192*2) + 8192.

So for instance a bend of -50 cents gives:

(-0.5*8192*2) + 8192 = -8192 + 8192 = 0 as you'd expect.

Similarly +50 cents gives 2*8192 or 16384 though you can only send 16383 (as 127*128 + 127), so if you want to do +50 cents do it as next midi note number -50 cents.

The zero position is 8192 = 64*128 + 0 so you need coarse pitch bend 64 and fine pitch bend 0 to reset to 0. This is the same as for normal midi pitch bends.

Example
So for instance Now input note 60 will be retuned to midi note 62, with pitch bend = 64 + (32*128) = 4160

So now, when you press midi note 60 on your keyboard, the output note is midi note 62 bent downwards in pitch. To find out how much it is bent downwards we need to convert the 4160 into a pitch bend e.g. in cents.

How to find the bend in cents from the pitch bend number
This is mainly of interest to synth authors who want to write their own version of this script to process the messages.

Since a change of 8192 pitch bend units gives a pitch bend of 50 cents, then to calculate the pitch bend in cents use the formula 50*(n - 8192)/8192

So in our example the bend for our example of 4160 is 50*(4160-8192)/8192 = -24.609375 cents

Why the pitch bend range is hard coded for these messages
If you make the pitch bend range adjustable then this introduces possibilities of intonation errors due to mismatch of range between the retuning software and the synth. In my expeience this is the most common reason for pitch issues when using the pitch bend retuning method.

Also, there is no benefit in options to adjust this to a wider pitch bend range such as two octaves etc, when we already have pitch glides through the entire midi range of pitches.

With standard pitch bends you can achieve wide pitch glides by changing the range, but only at the expense of sensitivity as the pitches then can't be defined so precisely. With the velocity keyswitches retuning, you can change any midi pitch to any other pitch through an ultra-smooth glide throughout the entire midi pitch range.

This makes no difference to normal pitch bend processing
This +- 50 cents pitch bend range is just for the purpose of this tuning message. The normal pitch bend range is unaffected, and the script author, and indeed the user, don't need to know what it is.

Indeed, in some situations a developer has no way to access the pitch bend range. You can find out what it "should be". But midi instruments are not required to recognize the midi pitch bend range message. So, there may be no way to know if your instrument has responded to thse messages. Many instruments have their own custom ways to set the range, sometimes hard coded.

It is also possible for an instrument to respond to pitch bends in a non standard way e.g. to be more sensitive to upward bends than to downward bends (or vice versa) - or behave in other ways. For an extreme example of this, in Tune Smithy I have an option which lets the program respond to pitch bends using "pitch ripples" with greater sensitivity in vicinity of pre-defined pitches, e.g. could be, that you have more sensitivity in the vicinity of just intonation ratios - large changes in the pitch wheel adjust the pitch slowly at first when close to a ratio like 5/4 - and then more rapidly as you move away from the just intonation ratio.

In the Kontakt script, I have no idea what the pitch bend range is, and don't know of a way to find it out. In the case of the Kontakt pianos, it is normally hard coded to zero; they don't respond to pitch bends at all. There seems to be no standard way for other scripts to access this information (not surprisingly due to the flexibility of the scripting language), and often the scripts are password protected so you can't see what they do.

It is surely best just to completely ignore the way the instrument responds to pitch bends normally, and base the spec. around a pre-defined fixed pitch bend range. In our discussion in the Xenharmonic Alliance, we all agreed on this.

Why is the range +- 50 cents instead of +- 200 cents
First of all, it adds no benefit to have a wider pitch bend range. We already have unlimited range pitch glides throughout the entire range of midi notes. This is done with a sequence of output note changes, and coarse and fine adjustments.

Note that the output note changes here are only used to set the pitch of the note during the glide. They are not intended as a hint to the synth what sample to use to achieve that frequency. See

50 cents is a natural standard to use as it is the smallest pitch bend range which makes it possible to achieve all possible notes.

Originally the script did use the standard range of +- 200 cents. But I was surprised to find out how much this complicates the script. The main issues were


 * 1) What do you show on the knobs? If they have a range of +- 200 cents instead of +- 50 cents, this makes it much harder to set and to read, and is less intuitive e.g. if the knobs show 60 + 150 cents then it is not nearly so easy to see that this is just 61 shifted up 50 cents, with a glance at the screen.
 * 2) Internally any pitch can have several different representations e.g. 60.5 = 60 + 0.5 = 59 + 1.5 = 61-0.5 = 62 - 1.5

It is much simpler if every possible pitch has only one internal representation in the tuning table.

Of course you can just simply read the pitch data as it is received in the +- 200 cents format and then immediately translate it to the +- 50 cents format before you process it further or display it to the user. This could be done if it was thought very important to use the +- 200 cents range. But that is less transparent, what you see on the user interface doesn't match what the instrument receives via midi. And I can't see any benefit to it at all, except familiarity. If user has a routine to translate cents into pitch bend numbers, they just need to add a factor of 4 to the routine to get the desired pitch bends, a trivial change, especially compared with the complexity of coding required of a synth writer to support +- 200 cents.

The aim is to make a method that is easy for synth writers to code, as easy as possible. Based on my experience for the Kontakt script I think a range of +- 50 cents is going to be easier to code as it is mainly a UI and visual display issue which would be equally tricky no matter how the UI is handled internally.

It is not just simpler for the synth authors. Apart from the unfamiliar extra factor of 4, the rest of the coding to send the note is also simpler. Given a note say 63.86, to decide how to send it, simply find the nearest midi note number 64, the bend -0.14 in this case, and then output the messages to retune to 64 - 0.14 cents. Is hard to think of a situation where it would be useful to send this same pitch as e.g. 64 - 1.14.

Behaviour during long pitch glides
Normally for a sample based instrument, you would expect the synth to use the nearest available sample to the desired pitch at the start of a glide, but what happens after that is up to the author of the instrument.

During long pitch glides, then the instrument can either continue to use the same sample as before (so leading to change of note quality when well away from its original pitch) or it can morph to new samples, or behave in some other way.

For techy reasons, in this Kontakt script, then the sample used depends on the original output note at the beginning of the glide. It then continues to use this same sample no matter how far you adjust the pitch during the glide.

Higher pitch precision
I've added an optional extra fine pitch bend message (see below) so that the numbers can be displayed accurately in Kontakt, and because Kontakt works internally with millicents, or a thousandth of a cent. This divides each of the pitch steps into a further 128 finer steps giving a resolution less than 0.00005 cents. Most programmers will neither need or want to do this I imagine.

How to ignore incomplete and non well formed instructions
If you receive any midi note apart from 126 or 127 on a channel, that counts as an "end of instruction". If the previous instruction hasn't been completed at that stage the whole thing should be ignored.

So for instance

The 127, 4 should be ignored as an incomplete instruction. You only do the retune when you receive the fine pitch bend value.

The same thing happens if the 127, 4 is interrupted by another instruction byte

The first 127, 4 should be ignored as an incomplete instruction.

How to ignore unsupported instruction bytes
If you receive an instruction byte your synth doesn't recognise (e.g. could be the 125 or 124 above) then you should ignore all the "data" received until you next encounter an instruction byte you do recognise.

An unsupported instruction byte will also interrupt the data so

All the data from then on is discarded, until the next recognized instruction.

Also, the two bytes of the incomplete 127, 4 are discarded.

Optional instructions (most synths and most retuning software will ignore these)
With 126 instructions available 1 to 127, and only eight of them used so far (including the 127 for data 0), there is lots of room for expansion if more instructions are needed.

Set displayed tuning description, definition and per note descriptions
The first of these is already implemented in the example script for Kontakt:

You send both of these at the end after all the notes are retuned.

Gets erased by any retune instruction - idea is if you retune a note the description is no longer valid.

You send this after the note is retuned and is erased by any retune instruction for that input note.

Extra fine pitch adjustment
This is also implemented in the example script. Is useful because it lets you display the cents values accurately to about 3 decimal places. In most situations you won't hear any difference as a result of such a tiny change, even in chords, but, in some rare situations e.g. with polyrhythmic beaeting partials, it might make a difference to the sound.

where e = extra fine pitch adjustment (gets you to millicents precision).

Since this instruction sets the extra fine adjustment for the MOST RECENT NOTE RETUNED it has to be sent AFTER THE NORMAL NOTE RETUNE.

So to send a note with extra fine pitch resolution:

where n=input note, m = output note, c = coarse, f = fine pitch bend, e = extra fine pitch bend

Indeed if you want to permit transmission of the data at very fine resolution you could also have

and so on up to as many bytes of extra resolution you want. Nobody else needs to understand these messages, it is totally acceptable to ignore them - so if anyone wants to add this capability, probably so they can display the incoming data in destination synth, causes no problem to anyone else.

Multi channel and mono tuning mode
This is an optional instruction

In mono mode then a velocity tuning instruction in any channel updates the tuning in all the channels.

These instructions are ignored in the Kontakt script because there is no way for a Kontakt instrument to adjust the tuning of instruments in other channels.

Set the pitch of the 1/1 and set a ratio value for a note
Similarly you could have extra instructions to set a ratio value.

This optional feature is already implemented in the example Kontakt script

For ratio value, this has to be sent after the note is retuned.

Synth should erase the ratio value when note is retuned.

I think that's the only way to do it (otherwise you would have to have a "reset ratio" insruction and send that every time you tune a note in case it's had a ratio assigned to it previously).

So for example to send the ratio 5/4

To send the ratio 256/243

That is enough to get you up to 16383/16383

Synth would calculate it as 128*2 + 0 = 256 128*1 +105 = 243

For larger numbers just repeat the process - find the value mod 128 send as data, divide by 128, and repeat as often as needed until the number reaches 0.

To parse this in receiving synth, to permit receipt of 3 or more bytes, do something like this (taking denum as example):

To set the pitch of the 1/1, set the numerator and denominator of any note to 1/1 like this:

Here if you don't want the 1/1 to be any of the notes in the tuning, e.g. for a CPS set, then is no problem, you can just temporarily retune e.g. midi note 0 to the desired pitch for the 1/1 and once it is set, retune it again to whatever you want it to be).

The 1/1 defaults to middle C if not set.

The ratio would not normally change the pitch of the note, just change the way the note is displayed. In any case, for compatibility with synths that ignore this data, the ratio information should not make a noticeable difference to the tuning.

If the note is already at the correct pitch (ratio to the 1/1) to a reasonable tolerance (say within a tenth of a cent or whatever), then it is permitted to retune it to the exact ratio on receiving this instruction.

Other options
For other ideas see the Discussion tab of this page

Alternative methods - pitch bends with channel remapping, and polyphonic pitch bends
You can do a fair amount with pitch bend retuning within the midi standard without use of tuning tables.

Channel remapping
This uses "instant pitch bends" played before the note, and remapping notes to different channels. It can be surprisingly effective, and this is what most of microtonal retuning programs usually do. For a simple example, to retune to 24-et you need just two channels, one tuned to concert pitch and one tuned 50 cents sharp. Then you can play any notes, and chords, simply by selecting the appropriate channel.

With other tunings you need more channels, but with 16 midi channels available, there is no problem at all retuning notes with up to 16 notes per octave, and many other scales can be tuned, including non octave ones, if you change the pitch bends for the channels from time to time as the notes are played depending on the requirements of the notes currently in play.

That's what my Tune Smithy does and Scala and many other programs nowadays such as Alt Tuner etc.

However the result is that you need many more channels than you need for a normal midi piece.

If you have different controllers, stereo pan positions, polyphonic instruments etc then you can easily run out of channels, especially with e.g. full orchestral work.

It is also inconvenient to use with a DAW or VST host or similar situation, because you have to load the instruments multiple times in different channels.

Instruments locked to twelve equal or limited pitch bend range
Also you may find that the instruments are set to different pitch bend ranges, and many instruments are locked into twelve equal. Many of the Kontakt instruments default to either locked into twelve equal, or much smaller pitch bend range than the standard range.

How to unlock Kontakt pitch bending

Polyphonic pitch bens
Another idea is to add polyphonic pitch bends support. The idea there is to disable the pitch bend wheel during a note, so the pitch bend only applies to the note on onset. This lets you play many notes at once with different pitch bends in the same channel. However it does have disadvantages. Mainly that you can't use the pitch bend wheel to bend notes after they are tuned.

Some musicians make extensive use of pitch changes after the note is played, as glides or as pitch vibrato. So it would be a big handicap for some musicians to disable this competely.

You can also run out of notes in some situations with polyphonic pitch bends. This is an artificial example - but if you want to play, in decimal midi, 59.6 59.7 59.8 59.9 60 60.1, 60.2, 60.3, 60.4 simultaneously and if the pitch bend range is limited to say 200 cents then you will run out of notes that can be bent into range.

You could bend 58, 59, 60, 61 and 62 into range but no more notes. Plus you can't re-use those notes and play them twice because then when you release the key is no way to know which one you mean to switch off and would probably switch both off.

Midi tuning standard
The midi tuning standard method uses sysexes. It works fine but few synths implement it, notably the NI FM7 (but support for it is broken in FM8) and some Proteus keyboards. Also some VST hosts strip sysexes, for instance Ableton Live does. It is not possible to add support for MTS sysexes to Kontakt instruments since the Kontakt scripting language doesn't provide any way to access sysexes.

For more about this see MIDI Tuning Standard (Wikipedia)

Other proposals we looked at, for retuning using undefined controllers, undefined RPNs, other methods with velocity keyswitches and using undefined Midi messages
See Other proposals we looked at, for retuning using undefined controllers, undefined RPNs, other methods with velocity keyswitches and using undefined Midi messages

The gnarly Kontakt scripting language
I thought I'd say a bit about the language for programmers who may be new to it. Some of my script may seem strange, and hard to follow, if you don't know about this.


 * There is no way to receive text input from the user. You can however open and save arrays using load_array and save_array in response to a button.
 * You can only declare variables in "on init" - which is called when the instrument is initialized or the script is loaded.
 * All the variables are globals.
 * All the variables have to be integers or strings; it has no floating point format. You can display these integers as fixed point decimals to the user however, so for instance declare ui_knob $Cents(-50000, 50000, 1000) declares a ui knob with a range of -50000 to 50000 but the numbers are all divided by 1000 before they are shown to the user, so giving a display that shows millicents.
 * No exponentials or logs
 * Integer variables all must begin with the symbol $, arrays must begin with %, and strings must begin with @
 * It uses # for not equal (most languages use !=), := for assignment and = for test of equality.
 * User declared functions can't have arguments passed to them
 * Some predefined variables such as $NOTE are valid only in the original handler e.g. that one is only valid in "on note" and "on release". They are NOT VALID in functions called by those handlers.
 * When you create knobs and other controls in the ui, you need to set a range of values e.g. declare ui_knob $Note(0, 127, 1)
 * This means that the variable $Note has a range of 0 to 127, and no other values can be stored in this variable, even temporarily. So you need to declare other variables if you want to do any calculations which may go outside the range set in the process of the calculation.
 * Some instructions can't be skipped with if end if conditions. The declarations obviously, but also "make persistent" is always executed. The only way to not make those variables persistent is to remove that part of the code or comment it out. The same also applies to SET_CONDITION(NO_SYS_SCRIPT_RLS_TRIG) which is why I comment it out in the version without release triggers

Removing some of these restrictions with Nils Liberg's Kscript editor
Some of these restrictions can be lifted using Nils Liberg's Kscript Editor. For instance he lets you have "inlined functions" which have parameters and are inlined during compilation. See inlined functions. Also, he lets you declare local variables variables, see comparison of Nils Liberg's variables with the pure Kontakt language

The exponentials and logs can be added using Nils Liberg's Kscript Editor together with Bob Villwock's Math Library for Kontakt

If you do that, the script gets converted to a "compiled script" for pasting into Kontakt.

I don't know of any way to add text input from the user. That is probably impossible - well you could get the user to use some tool to convert their text into numbers, and then paste those numbers into the script, but numbers can only be pasted in individually, one at a time. I can't see any practical way to e.g. let the user paste a Scala scale or a .tun tuning file into the program.

The velocity retuning script is a pure Kontakt script
I wrote the script however as a pure Kontakt script, although I used Nils Liberg's Kscript Editor for the syntax colouring and compilation checks for errors. I also used Bob Villwock's math library - what I did is to create a simple script using Log2, and then compiled it in Nils Liberg's Kscript editor, and then copied the output of that into my own script to add Log2 to it, Exp2 and other functions could be added similarly if you want to keep to a pure Kontakt script throughout.

My motivation for using the pure language is first inclination, I like working at a "lower level"; but it also makes it easier to merge it with existing scripts in the pure Kontakt language.

It is forwards compatible with KScript, you can add this code to any existing script in Nils Liberg's and Bob Villwock's extension to the language and it will work fine.

Useful external links for the Kontakt Scripting Language
This is for developers who want to write their own Kontakt scripts, I used some of these links when writing this script


 * KSP Reference Manual
 * The Kontakt Script Language - NI Kontakt Script Language ManuaL
 * Kontakt Scripting Tools
 * Nils Liberg's KScript Editor
 * Soniculture Scriptorium - I didn't use this but may be useful
 * How To Create Scripts In NI Kontakt, Part 1 - SOS tutorial
 * Kontakt scripting workshop - place to ask questions about Kontakt scripting
 * KONTAKT: Sampling, Programming & Scripting - a lively Kontakt scripting board in the Virtual instruments composer's forum
 * Introduction To Scripting in Kontakt, Part 1 Tutorial by Toby Pitman of NI.

Monster keyboard instruments with hundreds or thousands of keys, using this keyswitch method
Some keyboards available or under development have huge numbers of keys such as the Tonal Plexus Keyboards by Hi Pi Instruments, with up to 1536 keys.

Other instruments with more than 123 keys include Terpestra keyboard with 280 keys with plans to make it microtunable in its kickstarter project, Starlabs Microzone U-648 with 288 keys, their Ztar with 144 keys plus 6 note-assignable triggers, the four quadrant Lambdoma keyboard with 256 keys, and the Opal sonome with 192 keys.

Usually these work by splitting the notes across several channels. The TPX variety of Tonal Plexus uses 105 and 106 notes of each MIDI channel in an octave. The Lambdoma keyboard splits over 4 channels each with 64 notes.

However, the [https://www.facebook.com/photo.php?fbid=589357484447453&set=pb.414318895284647.-2207520000.1380210065. Megaplex, only available by special order], uses two channels per octave, and 128 notes per channel, and has 1536 keys in the six octave version.

Even keyboards that need 128 notes per channel can still be used, so long as you switch off the tuning after you update the table. See

Monster keyboards with e.g. 10,000 keys all playing distinct pitches in a single channel
What if you want to build a monster keyboard able to do velocity keyswitch retuning directly, with its own built in software to convert key presses into appropriate midi messages to play the desired pitches?

At first it might seem that such a keyboard would be limited to 128 keys per midi input channel. But with tuning tables, actually you could design a keyboard with any number of keys, say 10,000 keys (100 by 100 array), all playing distinct pitches and all played on a single channel. The only restriction is that you can't play chords with more than 128 notes held down simultaneously all in the same channel.

I thought it might help to explain how this is possible, by sketching a possible design for a monster keyboard like this. I am assuming that the keyboard has an embedded microchip which is used to translate the key presses into a stream of midi notes.

I have no idea how such chips are programmed, but the concept behind it is simple. The idea is to dynamically reassign the midi note numbers to keys. Only the keys that are actually held down at any time need to have a midi note number assigned to them.


 * 1) Internally each key has its own id, not limited to the 0 to 128, as it is not using midi at this stage. Could be voltages or 16 bit numbers or whatever it is the key sends to identify itself. So for a 10,000 key keyboard, then each key sends a different number from 0 to 10,000 to the internal chip that converts the key presses into midi messages, this is the key's id.
 * 2) the chip has an internal table of 10,000 entries which keeps track of the midi note numbers assigned to these ids. It doesn't matter how this is done, but to take an example, to start with, it could be set to 0 to 127 for first 128 keys, and then remaining keys assigned number -1 meaning not in use.
 * 3) The chip has another internal "lock" table of 10,000 entries, initialised to 0. As soon as you play a note, that number is marked as locked - its entry in the table is set to 1. When a key is locked, its assigned midi note number can't be changed.
 * 4) When you release the key it unlocks its number so it can be reassigned.
 * 5) When you press a key that doesn't have a midi number assigned (current note number -1), then the program on the microchip will look through the table for a key that is not currently held down. It then will then swap with that key. It sets that old key's note number to -1 meaning not assigned any midi note number, and use its number as the midi note number for the new key.
 * 6) Before it sends the new note number as a note on event, it sends the sequence of high keyswitches needed to retune that note to the correct output note on the destination synth.
 * 7) At any time no more than 128 of the keys have midi note numbers assigned, and the remaining keys are assigned -1 = not assigned.

Then we can assign any pitch in the midi range to any of these 10,000 keys. The only limitation on the keyboard is that you can't hold down more than 128 notes simultaneously.

There might be other ways to do it, but this method would work. The only question is how easy or hard is it to program on a microchip? That takes us beyond my realm of expertise, would be easy in C code such as what I write, and surely is possible at least.

C-code sketch for monster keyboard
Here is an idea of how you might do it - monster keyboard c-code sketch. It is just done in code as a way to present the idea which may be more readable for some programmers, not actually tested.