Writing Docs Gigedit SFZ Instrument Scripts NKSP Language NKSP Reference

LinuxSampler 2.1.0

LinuxSampler 2.1.0 and friends were released on November 25th 2017. Two years have passed since the last release of LinuxSampler. Here is a summary about what's new.

Real-Time Instrument Scripts

In the previous release a major new feature called Real-Time Instrument Scripts was added, which are essentially small programs that may be bundled with sound files to extend the sampler with custom behavior specifically intended for individual sounds. Find out more ...

These programs are written by sound designers in a script language called NKSP. In this release a large amount of extensions and improvements have been added for this real-time instrument scripting support of LinuxSampler. For example 48 new built-in functions and 21 new built-in variables have been added. Find out more ...

Also the NKSP language and the underlying engine itself was extended. Most notably the script engine now has an execution scheduler which is the basis for many of the timing relevant new NKSP features in this release, like programmatically suspending and resuming scripts for an exact duration or at an exact point of time or triggering or killing notes at very precise times (all with microsecond accuracy). You can now even launch new threads in your NKSP scripts by calling the new built-in function fork(). Furthermore bitwise operators have been added to NKSP, as well as support for read only built-in variables, "synchronized" code blocks , as well as user declared functions and user declared const array variables have been added to the NKSP language, and finally automatic suspension of RT threatening scripts by the RT script engine has been implemented. The latter ensures that the sampler remains stable, and does not cause audio dropouts, even while you are working on heavy and extremely buggy scripts. Also syntax error messages with NKSP scripts have been improved to output more clear and user friendly error messages, as well as the NKSP editor API has been improved which brings handy new features to gigedit's NKSP script editor, which will further be described below, along with gigedit's new features.

SFZ Engine

The SFZ engine now supports <global>, <master> sections, #define statement and set_ccN opcode. And finally the SFZ engine now supports NKSP real-time instrument scripts as well by adding a new script opcode for this purpose. So NKSP scripts are no longer limited to our Giga engine.

And yes, as you can see from the SFZ opcode links here, we also started documenting the actual SFZ file format. You wanna help us on completing the SFZ file format documentation? Great! Have a look at how articles are written for this site and get in touch with us!

New GigaStudio format features

The equally named software on Windows has gone years ago, but the format lives on with LinuxSampler and this release adds yet some more new extensions to the gig format.

Most notably you now have options to control envelope generators' state machines. For example you can now define whether a certain EG state should either be aborted or continued to its end when a note off arrived (or on a note on in the release stage). These controls are especially useful for certain kinds of sounds like percussive instruments.

Accordingly you will now find new check boxes for this in gigedit. As these are extensions of the original format, setting these options will only work with LinuxSampler and would be ignored with the original GigaStudio software.

Instruments DB

Also the Instruments Database feature has received important maintenance fixes. Before this release, the instrument DB feature was barely usable for quite some time. Fundamental instruments DB issues have been fixed in this release to finally consider this feature stable again as well.

Gigedit 1.1.0

Also Gigedit, our instrument editor for the GigaStudio/Gigasampler format, had been enhanced quite a lot. The most important new features are summarized next.

Script Editor

Gigedit's integrated instrument script editor supports now tight coupling directly with LinuxSampler's actual real-time instrument script backend. That provides several improvements for the script editor.

For example colored syntax highlighting of scripts is now always displayed correctly and simply looks much better now. Previously there was some small hard coded script parser code on Gigedit's side which however was buggy and simply did no great job. Now all the heavy lifting of handling all the details of the numerous NKSP language aspects are handled by the sampler instead, which also provides the following new script editor features.

Due to that direct coupling with LinuxSampler's script backend, gigedit's script editor now shows all issues related to the script (errors and warnings) directly within the script editor in real-time while you are typing. The actual erroneous locations of the script are automatically highlighted with red background color, locations of the script with warnings are automatically highlighted with yellow background color, and when you move your mouse over the respective code location, the precise error/warning message is displayed as a tooltip. And last but not least there is a summary of issues displayed in the status bar of the script editor. Since LinuxSampler's instrument script backend is actually doing all the work for the script editor, all aspects of the language, all details about built-in functions and variables, and all potential issues with their precise cause and messages are automatically covered by the script editor now. That way you immediately know whether or whether not your script is OK with every character you are typing, and without requiring to actually load the script with an instrument into the sampler.

Additionally when clicking on the script editor's "Apply" button or using Ctrl+S keyboard shortcut, then the script is automatically reloaded by the sampler. So you no longer have to reload the respective instrument manually while you are developing instrument scripts.

There are also visual enhancements for the script editor, for example the line numbers are now shown on the left, the font size can be altered by the user, and unused code portions (i.e. disabled by NKSP preprocessor statements) are automatically striked through. That way you can immediately see which code portions of your scripts are actually used, and which are not. Everything you see striked through is completely ignored by the sampler.

As as side note, you may have noticed a handy new built-in preprocessor condition in LinuxSampler 2.1.0 which can be enabled with SET_CONDITION(NKSP_NO_MESSAGE) and allows you to quickly disable message() function calls, i.e. to conviently switch your scripts between a debug and release mode. Find out more ...


Another major new feature in this release are macros. A macro is a set of changes that should be applied to the currently selected instrument.

Such macros can be reviewed and edited, and they can be saved permanently as templates or shortcuts for common instrument creation tasks. Macros can be assigned to F keys on the keyboard so that they can quickly be triggered, you can transfer them over the OS clipboard and you can write comments to your macros so that you never forget what kind of purpose you had in mind for them. Your macros will also appear in the application's menu, and when you move the mouse pointer over a macro, a tooltop appears with the comments you wrote for that macro.

The macro features are based on libgig's new "Serialization" framework (described below) and accordingly you need at least libgig 4.1.0 for using these macro features.

This is an example of editing a macro. Usually you may start creating a new macro by simply taking all parameters of a selected dimension region. Then in the macro editor you usually multi-row select (i.e. by Ctrl clicking items in the list) just the parameters you want this macro to alter, then click on "Inverse Delete" to just keep those few selected parameters in that macro. As a result, when you are going to apply this macro during your upcoming work, only those few parameters are modifed by this macro and all other ones are left untouched. Of course you can also alter the individual parameter values in this macro editor as well.

You might now think, wait a minute, does such a macro change the entire instrument, or only a portion of it? The answer is simple: you decide! The precise scope a macro is going to modify behaves exactly the same like you manually changed individual parameters in Gigedit before. That means for example when you check the two check boxes "all regions" and "all dimension splits", then when you trigger a macro, it is going to be applied against the entire instrument. If you uncheck those check boxes and select only one specific region and one specific dimension region zone, then the macro only modifies this single dimension region zone. Or yet another alternative: Ctrl+click the precise dimension region zones you want to be changed by the macro and then trigger the macro, i.e. by hitting the macro's F key on the keyboard, or by selecting the macro from the main menu.

So as you might see, macros introduce a powerful way for you to create yourself a personal instrument construction kit, not limited to only creating global templates for entire instruments, but also for an arbitrary set of small and large building blocks in any size and complexity you need. For example you may create a macro which only sets one single parameter, and another macro which configures an entire filter block with all its filter parameters and MIDI controllers, up to a macro which really modifies every single parameter to build up an entire instrument with one stroke of a key.

Persistent Settings

All user settings of gigedit are now persistently saved and automatically restored. This also includes gigedit's windows' dimensions and positions, and of course including all macros you create.

Multi-Row Selection

Multi-row selection has been added to all list views now, so you can now more efficiently apply actions to multiple samples, instruments or scripts simultaneously at once, instead of requesting those actions for each item individually. This works exactly like you are used to from other applications. So i.e. press and hold the Ctrl key while clicking with the mouse on the individual instruments (or samples) from the list view. Or press and hold the Shift key and click on an item from the list to select an entire range instead with one click.

Multi-Zone Selection

Also modifying key features of several dimension region zones simultaneously is now supported. That means you can now delete, split and resize multiple dimension region zones at once. Oh yes, I forget, Ctrl+click selecting multiple dimension region zones is supported now as well. For the latter there is also a keyboard shortcut now: Hit and hold the Alt and Shift keys, then use the left and right arrow keys to multi select the dimension region zones you need.

Feature Icons

You will also note that there are now icons displayed on the individual regions and dimension region zones. Those icons visualize common key features of regions and dimension region zones. For example if you forgot to assign any sample to one of them, then you will see a red dot on the respective region or dimension region zone. Another icon type is showing you whether a region or dimension region zone uses a sample loop. For example when you just imported a short drum sample (not a drum loop), then you don't really want a loop to be on for it. This way you can immediately see and control the key features of all regions and their dimension region zones, without requiring to browse through all of them individually.

Keyboard Shortcuts

Various new keyboard shortcuts have been added so you can work more efficiently on your sounds. For example you can now use Ctrl+Up and Ctrl+Down to switch between instruments, or use Ctrl+Left and Ctrl+Right to navigate through all regions of the currently selected instrument, and likewise you can use Alt+Left, Alt+Right, Alt+Up and Alt+Down to navigate through all dimension region zones of the currently selected region. Since there are many actions that can be either applied on file level, instrument level, on region level, or on dimension region level, as a general rule of thumb for all keyboard shortcuts:

So as another example you may copy all parameters of the currently selected dimension region zone to the clipboard by hitting Alt+C. Now when you change parameters of the selected dimension region, the original parameters are still there on the clipboard. Hit Alt+X to review or even edit the parameters directly on the clipboard. Then select a dimension region zone, or another instrument and then use Alt+V to apply those parameters from the clipboard to the now selected dimension region. You want to keep those parameters on the clipboard permanently in the editor for other instruments in future? Hit Ctrl+M to open the macro list, then hit Ctrl+B to save the content on the clipboard permanently as a new macro. From this point you can also simply duplicate the macro, fine tune and adjust the cloned macros and so on. All macros are saved along with the settings of the application. So they will always be there next time you launch gigedit, and no matter on which gig files you are working on.

Too many shortcuts to remember? Of course you can find all keyboard shortcuts in the menus and on the individual buttons. Simply place the mouse pointer over the individual menu items or buttons and a tooltip will explain what the action would do. For menu items and buttons you use frequently, start using their displayed keyboard shortcuts instead. And the ones you really are going to use frequently, you will remember as shortcut in a very short time.

Combine Tool Improvements

Also the Combine Tool has been improved. You can now simply select the (multiple) instruments you want to combine directly from the applications main window, i.e. by Ctrl or Shift clicking them from the instruments list view, and then right click to call the combine tool on that selection or even faster; simply hit Ctrl+j ("j" as in "join").

The Combine Tool now also shows you a preview of the order in which the selected instruments are going to be combined. This is especially useful when combining instruments with certain dimension types where the order significantly matters for the actual resulting sound; for example when combining by velocity dimension. Simply use drag n drop to reorder the previously selected instruments before combining them finally (by clicking on Ok or simply hitting Enter).

Search Filter

And last but not least a filter option field had been added to the instruments list view and samples list view, which allows you to find specific samples and instruments very quickly by typing search key words, which is especially very helpful in case you are working on huge gig files which contain a very large amount of samples or instruments in a single gig file (like this one, which apparently has far more than 400 instruments).

libgig 4.1.0

Our fundamental file access C++ library libgig has also received some major improvements, which are outlined next.

Files larger than 4 GB

libgig 4.1.0 adds support for writing files much larger than 4 GB (or more exactly: up to now 16 Exabyte = 16 777 216 Terabyte) for GigaStudio / Gigasampler (.gig), DLS, as well as for RIFF files in general. This file size limitation existed for a very long time due to the RIFF format's historical, internal 32 bit file offsets. To circumvent this file size limitation the concept of so called "extension files" was added in the past to the GigaStudio format, which means that the GigaStudio instrument editor (the original one on Windows) splitted the respective overall instrument file into a set of files (.gig, .gx01, .gx02, ...), each being max. 2 GB in size, and all of them were expected to be located in the same directory for the sampler to load the entire large instrument successfully. libgig always supported only reading such gig extension files, however libgig never supported to create .gig files with extension files, nor did it support modifying existing ones.

In this release it was necessary to finally get rid of this overall file size limitation in libgig. Now when that concept of extension files was introduced years ago, it made sense at that point, because there were still many systems out there which still had no support for large files (on either OS or file system level). However today even on low end mobile devices support for large files is already a broad standard. Accordingly instead of adding write support for extension files in libgig, the problem was addressed at its root by transparently using appropriate, automatic file offset sizes. So when writing .gig/DLS/RIFF files smaller than 4 GB there are still 32 bit file offsets being used by libgig. Accordingly such files are still backward compatible with older software. However if the overall file size to be written is 4 GB or larger, then 64 bit file offsets are automatically used by libgig instead. Note though that due to that circumstance such files ≧ 4 GB are not backward compatible with older versions of libgig, nor could they be loaded with the original GigaStudio software.

Serialization API

Another major new feature in this libgig release is the entirely new Serialization API which provides a powerful and easy way to serialize and deserialize an arbitrary set of native C++ objects into an abstract data stream. Which means you can simply save the entire runtime state of an application to a file or send it as data over "wire" (i.e. over network or to another process) and restore that runtime state from that data there at any time. In contrast to other C++ serialization frameworks out there, this framework provides two major benefits:

  1. This serialization framework is designed to be very robust regarding potential versioning changes of the native C++ classes being (de)serialized. So even if the C++ classes have seen massive software changes between the point where they were serialized and the point where they are to be deserialized; for example if class member variables of serialized C++ objects were renamed in meantime, or if variable offsets, or variables' data types had been changed, then the deserialization algorithm can still cope with such common software changes automatically in many cases, that is as long as the deserialization algorithm can "guess" what the changes were exactly. If the serialization framework is unable to automatically detect the precise software changes, then it will abort the deserialization task with an exception and an error message stating that the software versions are incompatible.
  2. This serialization framework supports "partial" deserialization. That means it not only allows to restore an entire runtime state, but it also allows to only restore an arbitrary desired subset of information from the previously serialized data stream, while leaving all other data of the running C++ objects untouched. The serialization framework also incorporates a reflection API which allows applications to view and manipulate the already serialized data, which in turn allows to implement convenient editors on top of such serialized data, i.e. allowing end users to pick or alter specific information within the serialized data.
This new Serialization framework is already embedded into the gig classes of libgig, and it is used as basis for the new powerful macro features in the gigedit instrument editor, like already outlined above.
Document Updated:  2017-12-06  |  Author:  Christian Schoenebeck