The EM Poll

Master Class: Scripting in Kontakt 3

Feb 1, 2008 12:00 PM, By Len Sasso

           

Use Kontakt's powerful script language to create custom instrument control panels and advanced MIDI processors.

BONUS MATERIAL
Web Clips: download a ZIP archive of all scripts covered in this Master Class, and more!

Blind Update

Script GUI elements are often used to access settings inside a Kontakt instrument. The simplest case is a script knob that sets an instrument knob. See “Script Examples,” example D, for the init and ui_control callbacks that control the instrument's Group 1 Source volume. The script knob displays volume in decibels, just as the instrument knob does.

An example of a built-in variable is $ENGINE_PAR_VOLUME. Built-in variables are automatically updated to reflect Kontakt engine settings, and you'll find variables for most parameters. Built-in variables are always uppercase, so your own variables will be easier to spot if you combine uppercase and lowercase letters.

FIG. 2: A little bit of formatting and renaming, as well as adding a custom skin, makes the script GUI easier to use.

Scripting can apply on the instrument or the group level. The last three numbers in the _set_engine_par and _get_engine_par commands (0,-1,-1 in example D) determine the group, slot, and module type affected. Group and slot numbering starts at 0; use a group value of -1 to access instrument-level parameters. (In the case of volume, setting the group to -1 addresses the main instrument volume.) Slot is used to select among multiple send and insert effects and modulators. Use a slot value of -1 when that doesn't apply. The last setting distinguishes instrument insert (1) versus send (0) effects or modulator routing. Use a value of -1 in all other cases.

When you have an instrument with several groups and you want to control a parameter (group volume, for instance) that appears in all groups, it's easy to set up a menu to select the group, and then use the same knob to control each group's volume. You'll find an example on p. 66 of The Kontakt Script Language manual that uses a group menu with volume, pan, and tuning controls (see Fig. 3). For convenience, I've included the script in Web Clip 1.

For 2-way communication, in which changes to the instrument knob are reflected in the script GUI, add a ui_update callback. That should be done with care, however, because ui_update is triggered whenever any instrument control is moved, and frequent callbacks may degrade performance (see “Script Examples,” example E).

If you want to use MIDI continuous controllers for script GUI elements, you need to use the controller callback. That's because you can't assign MIDI modulators directly to script GUI elements in the way that you can with instrument controls. As with the ui_update, the controller callback should be used with care; lots of incoming MIDI CC data can degrade performance, and it's almost always preferable to use Kontakt's robust MIDI-remote scheme. For how to map the 1-way volume knob to MIDI CC 11, see “Script Examples,” example F.

The ignore_controller command blocks the MIDI CC message from affecting all other instrument parameters. The $Volume value calculation ($Volume := …) converts the MIDI CC range of 0 to 127 to the volume knob's range of 0 to 1,000,000. Keep in mind that the KSP uses integer arithmetic; therefore, large value ranges are used to get high resolution. Time parameters, for instance, are scaled to microseconds, so a declared range of 0 to 1,000,000 in a script corresponds to a time range of 0 to 1 second.

Take Note

Note processing adds a new, and arguably more interesting, dimension to scripting. The factory library is full of note-processing scripts, and in the spirit of not reinventing the wheel, I've used one and scavenged another for the instrument shown in Fig. 4. It combines the Easy Chord Generator script (top of Fig. 4) from the Kontakt 2 library with a custom script that can either correct incoming notes or constrain them to a user-defined scale (bottom of Fig. 4). You may prefer to think of scale correcting as mode shifting (see Web Clip 2).

Notice that the chord generator script comes first. That illustrates an important point about scripting: each instrument holds up to five scripts, and they are executed in the left-to-right order of the tabs that select them. In particular, MIDI data entering the instrument passes through the scripts in that order. The chord generator needs to come before the scale fixer in the processing chain so that all chord notes, rather than just the incoming MIDI notes, are scale corrected.

FIG. 3: Use a menu to have the same GUI elements control different groups.

The scale fixer uses two 12-column tables. The upper table is one row high and serves to pass or reject notes matching the pitches in the legend above it. The cells in the lower table can have a value of either 0, 1, or -1, which indicates that the corresponding note will be either unchanged or shifted up or down a semitone. The settings in Fig. 4 allow all notes through but shift notes with accidentals down a semitone — in other words, the scale shifter corrects incoming notes to the key of C major.

The Root knob shifts the legend and, along with it, the scale to which the notes are corrected. The script for that was scavenged from the Fiddle instrument in the Kontakt 3 factory World library. To view the script for the scale correction, see “Script Examples,” example G.

Every incoming MIDI message is assigned an ID, and the ignore_event command prevents the incoming note from being played automatically. The variable $pitcla holds the pitch class (0 for C, 1 for Db, 2 for D, and so on) of the incoming note, and the variable $nupitcla is the pitch class of the note after the script adjusts for the root key. Because that calculation involves subtracting the pitch class indicated by the value of the Root knob, negative values can result. The first if…end if condition corrects for that. The second if…end if condition throws away rejected notes and plays passed notes with corrected pitches.

The declarations and clever handling of the note-names display and Root knob are lengthy but self-explanatory. They set the value of the variable $key_knob to the pitch class of the root key. That number is used to both rotate the note-names display and adjust the value of $nupitcla before the tables are applied. To see how this works, look at the script in Web Clip 1.

For clarity I've chosen short script examples to illustrate key points. Scripts are often huge and include a lot of repetition. Careful formatting and commenting makes them more readable. Keeping an archive of oft-repeated routines speeds up script writing. Above all, unless you're a glutton for syntax, keep the excellent manual handy.

Len Sasso is an associate editor of EM. For an earful, visit his Web site at www.swiftkick.com.