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!

A brief spin through the factory instrument library reveals the power of the Kontakt Script Processor (KSP). All the factory instruments have performance control panels that are visible when the rack is in Multi Instrument mode, and these panels are courtesy of scripting. Scripts provide access to essential controls as well as many forms of advanced event processing. Examples of this processing include automatic chord generation, step sequencing, arpeggiation, and much more.

This month's “Square One” column, “Read the Script,” gives an introduction on how to script using basic examples drawn from three software programs, one of which is Kontakt 3. In this “Master Class,” I'll pick up where “Square One” leaves off and reveal some of the power of KSP scripting. If you're new to scripting, I recommend reading “Square One” first. You'll find an archive of all the scripts from this article in Web Clip 1.

Before You Type

A lot of effort has been put into KSP scripting by Native Instruments as well as third-party developers, and they have created many useful scripts that are there for the taking. Kontakt 3 comes with a library of scripts of various kinds, and you'll find some useful scripts in the Kontakt User Library on the NI Web site (www.nativeinstruments.com/kontaktuserlib). Although scripts for third-party Kontakt instruments are often locked, you'll occasionally come across ones that are not. If you don't find exactly what you want, you may still get some useful hints.

It's a good idea to start your own library of script fragments. An example of how to add a fragment would be to take the several lines needed to declare a user interface element, position that element on the panel, name it, and set a default value for it. Filling in a few placeholders with the relevant data is much faster than retyping those three or four lines five or ten times.

Kontakt's Script editor is adequate for creating and testing short scripts, but using it for more-complex scripting can be tedious. Using an external text editor will save you lots of time, and there's no better choice than Nils Liberg's free KScript Editor (www.nilsliberg.se/ksp). While at his site, check out his collection of scripts and his excellent Kontakt scripting tutorial. You'll also find an active Kontakt forum with lots of scripting information at Virtual Instruments Composers Forum (http://vi-control.net/forum/viewforum.php?f=65).

Keep in mind that the script language is case sensitive and spaces are ignored. If you break up a long statement with “…”, it will still be processed as a single line. Comments, which are enclosed in curly brackets, do not slow down script execution, but they can make scripts cluttered. On the other hand, comments are very helpful when you revisit a script — so use them, but only sparingly.

Getting Gooey

As mentioned, creating control panels for use in Multi Instrument mode is an important application of scripting, and the process consists of several parts. First, you need to design the panel layout, which entails defining its individual controls, positioning them as desired, specifying how they operate (by setting value ranges, display units, text messages, and so on), and ensuring that they're visible in Multi Instrument mode. (You can always access script controls in Instrument Edit mode by clicking on the Script Editor tab.) Next, you need to link script controls to Kontakt instrument parameters, and that linking may or may not be bidirectional. You may want to set up MIDI remote control for panel elements. Finally, you might want to hide or show some elements depending on certain conditions or the settings of other elements. For instance, panels frequently have a button for toggling between easy and expert modes.

FIG. 1: GUI element declarations result in an ad hoc control panel that has enigmatic labels.

Graphical user interface elements are defined using declare statements in the init callback, as are other script elements such as variables, constants, and tables. Six types of GUI controls are available: buttons, knobs, numericals, menus, labels, and tables. See the sidebar “Script Examples,” example A, for an init callback that defines one of each.

If you try this script, you'll see that it leaves a lot to be desired (see Fig. 1). The graphical arrangement of the controls is ad hoc, the display names are the same as the declared names, and the panel disappears when you switch to Multi Instrument mode.

Script control panels are six rows wide by six columns high. You position elements with a move_control statement: move_control ($knob,1,2) would place the knob in column 1 of row 2. Setting either position to 0 hides the control. You can reposition controls in any callback, but it's a good idea to set their position in the init callback even if you plan to move them later in the script (for instance, when switching display modes).

You change the names of knobs, buttons, and numericals with the set_text statement: set_text ($knob,“Volume“). Although names can be any length, depending on the font, knobs typically display 7 characters, whereas buttons and numericals display 14. Use the set_text statement along with the add_text_line statement to fill in labels. The add_menu_item statement adds items to a menu and sets the values returned when items are selected. The order of the statements determines the order of the items in the menu. For an init callback that illustrates these points, see example B in “Script Examples.”

The first statement, make_perfview, causes the script's GUI to appear in Multi Instrument mode (see Fig. 2). The wood-panel background is not the result of scripting; rather, it is set in the Instrument options. But once you've selected a graphic in the Skin Bitmap box, the _set_skin_offset statement sets the vertical offset in pixels for the top of the panel. Skins should be Targa files that are 633 pixels wide; vertical offsets should be multiples of 225. So you need a 633 × 1,125-pixel graphic to have separate panels for each of the five scripts an instrument can hold.

Notice that button, knob, and numerical values are set with the := statement, as are variable values. Several unit options are available for knobs (I've used milliseconds in example B), and you can set a default value that applies when the init callback is executed or when you right-click on the knob.

So What?

There's not much point to a pretty control panel unless it controls something. That's where the other callbacks come in. Incoming MIDI note events trigger on note and on release callbacks. Incoming MIDI controller messages trigger on controller, on rpn, and on nrpn callbacks. Interacting with a script's GUI triggers on ui_control callbacks (there is a separate one for each declared control). Interacting with other Kontakt GUI controls triggers the on ui_update callback. That's how you establish 2-way communication between script and Kontakt parameters.

Only the init callback is required (unless the script is empty, of course). Other callbacks are used as needed for the task at hand. You can have more than one instance of the same callback, but it's better practice to use conditional branching within a callback to differentiate tasks triggered by the same type of action. See “Script Examples,” example C, for the callback that's associated with the button in Fig. 2.

The ui_control callback is triggered whenever the button is clicked. Clicking on the button named Press Me makes the knob disappear and renames the button to Show Knob. Clicking on the button again makes the knob reappear and renames the button to Hide Knob. Use variations on this theme to toggle between easy and expert panels or to manage more GUI elements than fit on a single panel.

Click to continue reading "Master Class: Scripting in Kontakt 3"

	Fill in the form below and click Order Now! to get two years (26 issues) for just $23.97 - the regular price of one year. But HURRY - this offer won't last forever! (U.S. orders only please)
First Name: Last Name: Address: City: State: Zip: Email:
This data will be sent directly to Electronic Musician Magazine  and will not be used for any other purposes.