Product Assembly¶

Now that we understand what nodes are, we need to learn how to assemble them into a working instrument. Every IVLS product is built from two key files: a build file and a product file.

The Product File¶

The product file (typically called ivls-product.ksp) is where you declare which nodes your instrument uses, and configure a few essential settings.

Let's look at a minimal example:

define ivls.THREADS := 1

define IVLS_NODES += MyFirstNode

define PRODUCT_GUI_HEIGHT := 540

import "_IVLS/builder.ksp"

Let's break this down:

ivls.THREADS tells the framework how many concurrent playback threads your instrument needs. For most instruments, 1 is fine. You would increase this for instruments that need to process multiple simultaneous note events in parallel, but that's a topic for later.

IVLS_NODES is the list of all nodes your product uses. You add your nodes here with the += operator. If you have multiple nodes, separate them with , ... (the ... is a line continuation):

define IVLS_NODES += MyFirstNode, ...
                     MySecondNode, ...
                     MyThirdNode

Every node you write must appear in this list, or IVLS won't know about it.

PRODUCT_GUI_HEIGHT sets the height of your instrument's GUI in pixels. Even if you haven't designed a GUI yet, IVLS requires this value to be defined.

The final line imports builder.ksp from the IVLS SDK. This is the entry point that boots the entire framework.

What builder.ksp Does¶

The builder.ksp file is remarkably simple. It does exactly two things:

Imports the IVLS core (ivls.ksp), which contains all of the framework's internal machinery
Registers the Voice cluster, which is the data structure that powers the playback system

You never need to modify builder.ksp. It's provided by the SDK and shared across all products.

The Build File¶

The build file (build.ksp) is the file you actually compile. It sets compiler options and imports your code. A typical build file looks like this:

{ #pragma compile_with remove_whitespace }
{ #pragma compile_with optimize_code }
{ #pragma compile_without compact_variables }
{ #pragma compile_without add_compile_date }
{ #pragma compile_without combine_callbacks }
{ #pragma compile_without sanitize_exit_command }

import "nodes/"

{ #pragma save_compiled_source ../Resources/scripts/my-instrument-compiled.txt }

The #pragma directives control how the KSP compiler processes your code. The defaults shown above are standard for IVLS products; you typically won't need to change them.

import "nodes/" imports your entire code folder. IVLS will recursively pull in every .ksp file in that directory, including your product file and all of your nodes.

The final pragma tells the compiler where to save the compiled output, which is the file Kontakt will actually load.

Compiling and Loading¶

To compile your instrument, open build.ksp in Sublime Text and press F5 (or use ivls compile in the terminal). The compiler will process all of your code through the IVLS preprocessor, resolve all node registrations, and produce a single compiled .txt file.

To load the result in Kontakt, open your instrument's .nki file and point its script slot to the compiled .txt file. The instrument will boot, IVLS will initialize all of your registered nodes, and you'll see any GUI you've configured.

At this point, nothing will play yet. We haven't set up any flows or voices. But the framework is running, your nodes are initialized, and their cb Init callbacks have executed. That foundation is what the rest of the guide builds on.