Load/Save Commands

General Information

File Formats

It is possible to load and save the following file formats:

Kontakt arrays (.nka files)
MIDI files (.mid) to be used with the file commands in KSP
Samples (.wav, .aif, .aiff, .ncw) to be used with Kontakt's convolution effect or user zones (loading only)

Asynchronous Handling

Loading and saving files cannot be executed in real time. This is why all load/save commands return a unique value upon completion of their action - the async ID. You can use this value in combination with $NI_ASYNC_ID and $NI_ASYNC_EXIT_STATUS within the on async_complete callback to check whether the the command has completed its action, and whether or not the loading or saving was successful.

Path Handling

All file paths in KSP use a slash character (/) as a folder separator. Backslash characters are not supported. The full path also has to start with a slash character /.

Examples

Factory folder on macOS:

/Library/Application Support/Native Instruments/Kontakt 7/

Factory folder on Windows:

C:\Program Files\Common Files\Native Instruments\Kontakt 7\

When loading or saving files with an absolute path, as opposed to loading from the resource container, always use path variables in combination with get_folder().

get_folder()

`get_folder(<path-variable>)`
Returns the path specified with the built-in path variable.
`<path-variable>`	The following path variables are available: `$GET_FOLDER_LIBRARY_DIR` If used with an NKI which belongs to a Kontakt Player encoded library: library folder. If used with an unencoded NKI: the User Content folder, which is found as follows: macOS: `/Users/<UserName>/Documents/Native Instruments/User Content/` Windows: `C:\Users\<UserName>\Documents\Native Instruments\User Content\` `$GET_FOLDER_FACTORY_DIR` The factory data folder of Kontakt, mainly used for loading factory IR samples. Note: this is not the Kontakt Factory Library folder! `$GET_FOLDER_PATCH_DIR` The folder in which the patch was saved. If the patch was not saved before, an empty string is returned.

get_folder(<path-variable>)

Returns the path specified with the built-in path variable.

<path-variable>

The following path variables are available:

$GET_FOLDER_LIBRARY_DIR

If used with an NKI which belongs to a Kontakt Player encoded library: library folder.

If used with an unencoded NKI: the User Content folder, which is found as follows:

macOS: /Users/<UserName>/Documents/Native Instruments/User Content/

Windows: C:\Users\<UserName>\Documents\Native Instruments\User Content\

$GET_FOLDER_FACTORY_DIR

The factory data folder of Kontakt, mainly used for loading factory IR samples.

Note: this is not the Kontakt Factory Library folder!

$GET_FOLDER_PATCH_DIR

The folder in which the patch was saved.

If the patch was not saved before, an empty string is returned.

Example

on init
    message(get_folder($GET_FOLDER_FACTORY_DIR))
end on

Displaying the path of Kontakt's factory data folder.

load_array()

`load_array(<array-variable>, <mode>)`
Loads an array from an external .nka file.
`<array-variable>`	The name of the array variable. This name must be present as the first line of the .nka file.
`<mode>`	0: A dialog window pops up, allowing you to select an .nka file to load. This mode can only be used in on persistence_changed, on ui_control and on pgs_changed callbacks (asynchronously). 1: The array is directly loaded from the `Data` folder. For user instruments, the `Data` folder is located beside the resource container. For Kontakt Player encoded library instruments, the `Data` folder is located here: macOS: `/Users/<UserName>/Library/Application Support/<LibraryName>/` Windows: `C:\Users\<UserName>\AppData\Local\<LibraryName>\` This mode can be used synchronously in on init, and asynchronously in on persistence_changed, on ui_control and on pgs_changed callbacks. 2: The array is directly loaded from the `data` folder inside the resource container. This mode can be used synchronously in on init, and asynchronously in on persistence_changed, on ui_control and on pgs_changed callbacks.

load_array(<array-variable>, <mode>)

Loads an array from an external .nka file.

<array-variable>

The name of the array variable. This name must be present as the first line of the .nka file.

<mode>

0: A dialog window pops up, allowing you to select an .nka file to load. This mode can only be used in on persistence_changed, on ui_control and on pgs_changed callbacks (asynchronously).

1: The array is directly loaded from the Data folder.

For user instruments, the Data folder is located beside the resource container.

For Kontakt Player encoded library instruments, the Data folder is located here:

macOS: /Users/<UserName>/Library/Application Support/<LibraryName>/

Windows: C:\Users\<UserName>\AppData\Local\<LibraryName>\

This mode can be used synchronously in on init, and asynchronously in on persistence_changed, on ui_control and on pgs_changed callbacks.

2: The array is directly loaded from the data folder inside the resource container.

This mode can be used synchronously in on init, and asynchronously in on persistence_changed, on ui_control and on pgs_changed callbacks.

Remarks

It is also possible to load real and string arrays from .nka files.
It is not possible to load an array named %xyz from an .nka file into array %abc. The variable names have to match precisely.
The array data is not directly available after the load_array() command has been executed, since the command works asynchronously. The only situation in which the values are instantly available is when using mode 1 or mode 2 inside on init callback.
When using mode 0, the callback continues even if the loading dialog is still open.
When loading an array within the on init callback, please note that the array will implicitly be made persistent (as if make_persistent() command was used) , which results in loaded data being overwritten at the end of the callback. Use read_persistent_var() before loading the array to avoid this problem.
.nka files loaded from the resource container should always have a newline character at the end of the file. If this last newline is missing, Kontakt cannot know the file has ended and will continue to try and load other data from the resource container. Files generated by the save_array() command have this automatically, but if you are creating NKA files via different means, this is something to be aware of.

Example

on init
    declare $count
    declare $load_arr_id := -1
    declare $save_arr_id := -1
    declare %preset[8]

    declare ui_button $Load
    declare ui_button $Save
    declare ui_table %table[8] (2,2,100)

    make_persistent(%table)
end on

on ui_control (%table)
    $count := 0
    while ($count < 8)
        %preset[$count] := %table[$count]

        inc($count)
    end while
end on

on ui_control ($Load)
    $load_arr_id := load_array(%preset, 0)
end on

on ui_control ($Save)
    $save_arr_id := save_array(%preset, 0)
end on

on async_complete
    if ($NI_ASYNC_ID = $load_arr_id)
        $load_arr_id := -1
        $Load := 0

        if ($NI_ASYNC_EXIT_STATUS = 1)
            $count := 0
            while($count < 8)
                %table[$count] := %preset[$count]

                inc($count)
            end while
        end if
    end if

    if ($NI_ASYNC_ID = $save_arr_id)
        $save_arr_id := -1
        $Save := 0
    end if
end on

Exporting and loading the contents of a ui_table widget.

load_array_str()

`load_array_str(<array-variable>, <path>)`
Loads an array from an external .nka file, using an absolute path to the file.
`<array-variable>`	The name of the array variable, this must be present as the first line of the .nka file.
`<path>`	The absolute path of the .nka file.

Remarks

The behaviour is similar to load_array() with mode set to 0, but instead of manually choosing an .nka file, you can specify it with an absolute path.
This command can be used synchronously in on init, and asynchronously in on persistence_changed, on ui_control and on pgs_changed callbacks.
When loading an array within the on init callback, please note that the array will implicitly be made persistent (as if make_persistent() command was used) , which results in loaded data being overwritten at the end of the callback. Use read_persistent_var() before loading the array to avoid this problem.

Example

on init
    message("")
    set_ui_height(2)

    declare $count
    declare $load_arr_id := -1
    declare %preset[8]
    declare @file_path
    declare @basepath_browser
    { set browser path here, for example:
    @basepath_browser := "/Users/<username>/Desktop/Arrays" }

    declare ui_file_selector $file_browser
    declare ui_table %table[8] (2, 2, 100)

    declare $browser_id
    $browser_id := get_ui_id($file_browser)

    set_control_par_str($browser_id, $CONTROL_PAR_BASEPATH, @basepath_browser)
    set_control_par($browser_id, $CONTROL_PAR_WIDTH, 112)
    set_control_par($browser_id, $CONTROL_PAR_HEIGHT, 68)
    set_control_par($browser_id, $CONTROL_PAR_COLUMN_WIDTH, 110)
    set_control_par($browser_id, $CONTROL_PAR_FILE_TYPE, $NI_FILE_TYPE_ARRAY)

    make_persistent(@file_path)
    make_persistent(%table)

    move_control_px($file_browser, 66, 2)
    move_control(%table, 3, 1)
end on

on async_complete
    if ($NI_ASYNC_ID = $load_arr_id)
        $load_arr_id := -1

        if ($NI_ASYNC_EXIT_STATUS = 0)
            message("Array not found!")
        else
            message("")

            $count := 0
            while ($count < num_elements(%preset))
                %table[$count] := %preset[$count]

                inc($count)
            end while
        end if
    end if
end on

on ui_control ($file_browser)
    @file_path := fs_get_filename($browser_id, 2)
    $load_arr_id := load_array_str(%preset, @file_path)
end on

Loading different table presets with a browser. Make sure to first set the browser path of the file selector to point to a folder with compatible .nka files.

load_ir_sample()

`load_ir_sample(<path-or-filename>, <slot>, <generic>)`
Loads an impulse response sample into Kontakt's convolution effect.
`<path-or-filename>`	The absolute file path of the IR sample. If no path is specified, the command will look for the specified sample within the `ir_samples` folder of the resource container. If no resource container is available, the folder `ir_samples` within the Kontakt user folder will be checked. The Kontakt user folder is located here: macOS: `/Users/<username>/Documents/Native Instruments/Kontakt 7/` Windows: `C:\Users\<username>\Documents\Native Instruments\Kontakt 7\`
`<slot>`	The slot index of the convolution effect (zero-based).
`<generic>`	Specifies whether the convolution effect is used as an: `$NI_SEND_BUS`: Send effect `$NI_INSERT_BUS`: Insert effect `$NI_MAIN_BUS`: Main effect For buses, this parameter specifies the actual bus: `$NI_BUS_OFFSET + [0 ... 15]`: One of the 16 buses

Remarks

Please note that any subfolders inside the ir_samples folder of the resource container will not be scanned, and it is not recommended to add them manually via text strings. Doing so could lead to problems, because subfolders will be ignored during the creation of a resource container monolith.

Example

on init
    declare $load_ir_id := -1
    declare ui_button $Load
end on

on ui_control ($Load)
    $load_ir_id := load_ir_sample("Small Ambience.wav", 0, $NI_SEND_BUS)
    $Load := 0
end on

on async_complete
    if ($NI_ASYNC_ID = $load_ir_id)
        $load_ir_id := -1

        if ($NI_ASYNC_EXIT_STATUS = 0)
            message("IR sample not found!")
        else
            message("IR sample loaded!")
        end if
    end if
end on

Load an IR sample into a convolution reverb, placed in the first slot of send effect chain.

save_array()

`save_array(<array-variable>, <mode>)`
Saves an array to an external .nka file
`<array-variable>`	The name of the array variable to be saved.
`<mode>`	0: A dialog window pops up, allowing you to save the .nka file. This mode can only be used in `on persistence_changed`, `on ui_control` and `on pgs_changed` callbacks. 1: The array is directly saved in the `Data` folder. For user instruments, the `Data` folder is located beside the resource container. For Kontakt Player encoded library instruments, the `Data` folder is located here: OS X: `/Users/<UserName>/Library/Application Support/<LibraryName>/` Win: `C:\Users\<UserName>\AppData\Local\<LibraryName>\` This mode can be used synchronously in `on init`, and asynchronously in `on persistence_changed`, `on ui_control` and `on pgs_changed` callbacks.

save_array(<array-variable>, <mode>)

Saves an array to an external .nka file

<array-variable>

The name of the array variable to be saved.

<mode>

0: A dialog window pops up, allowing you to save the .nka file. This mode can only be used in on persistence_changed, on ui_control and on pgs_changed callbacks.

1: The array is directly saved in the Data folder.

For user instruments, the Data folder is located beside the resource container.

For Kontakt Player encoded library instruments, the Data folder is located here:

OS X: /Users/<UserName>/Library/Application Support/<LibraryName>/

Win: C:\Users\<UserName>\AppData\Local\<LibraryName>\

This mode can be used synchronously in on init, and asynchronously in on persistence_changed, on ui_control and on pgs_changed callbacks.

Remarks

It is also possible to save real and string arrays into .nka files.
The exported .nka file consists of the name of the array followed by all its values, one value per line.
When using mode 0, the callback continues even if the loading dialog is still open.

save_array_str()

`save_array_str(<array-variable>, <path>)`
Saves an array to an external .nka file with the specified absolute path.
`<array-variable>`	The name of the array variable to be saved.
`<path>`	The absolute path of the .nka file to be saved.

Remarks

The behaviour is similar to save_array(), but instead of manually choosing a save location, you can directly save the file to the specified location.
If the file does not exist, but the folder does, a new .nka file will be created.
This command can be used synchronously in on init, and asynchronously in on persistence_changed, on ui_control and on pgs_changed callbacks.

Example

on init
    message("")
    set_ui_height(2)

    declare $count
    declare $save_arr_id := -1
    declare %preset[8]
    declare @path
    { set save path here, for example:
    @path := "/Users/<username>/Desktop/Arrays/" }

    declare ui_button $Save
    declare ui_label $pattern_lbl (1, 1)
    declare ui_text_edit @preset_name
    declare ui_table %table[8] (2, 2, 100)

    make_persistent(%table)
    make_persistent(@preset_name)

    set_control_par(get_ui_id(@preset_name), $CONTROL_PAR_FONT_TYPE, 10)

    move_control_px(@preset_name, 73 + (3 * 92), 2)
    move_control_px($pattern_lbl, 66 + (3 * 92), 2)

    set_control_par_str(get_ui_id(@preset_name), $CONTROL_PAR_TEXT, "<empty>")
    set_text($pattern_lbl, "")
end on

on ui_control (%table)
    $count := 0
    while ($count < num_elements(%preset))
        %preset[$count] := %table[$count]

        inc($count)
    end while
end on

on ui_control ($Save)
    $save_arr_id := save_array_str(%preset, @path & @preset_name & ".nka")
end on

on async_complete
    if ($NI_ASYNC_ID = $save_arr_id)
        $save_arr_id := -1
        $Save := 0
    end if
end on

Save table presets with custom names. Make sure to set the path where the .nka files will be saved.

save_midi_file()

`save_midi_file(<path>)`
Saves a MIDI file with the range specified by the `mf_set_export_area()` command.
`<path>`	The absolute path of the MIDI file to be saved.

Example

on init
    message("")

    declare $save_mf_id := -1
    declare @path
    { set save path here, for example
    @path := "/Users/<username>/Desktop/MIDI Files/" }

    declare ui_text_edit @file_name
    declare ui_label $file_name_lbl (1, 1)
    declare ui_button $Save

    make_persistent(@file_name)

    set_control_par(get_ui_id(@file_name), $CONTROL_PAR_FONT_TYPE, 10)
    set_control_par_str(get_ui_id(@file_name), $CONTROL_PAR_TEXT, "<empty>")

    set_text($file_name_lbl, "")

    move_control($Save, 2, 1)
    move_control_px(@file_name, 73, 2)
    move_control_px($file_name_lbl, 66, 2)
end on

on ui_control ($Save)
    $save_mf_id := save_midi_file(@path & @file_name & ".mid")
end on

on async_complete
    if ($NI_ASYNC_ID = $save_mf_id)
        $save_mf_id := -1
        $Save := 0
    end if
end on

Saving a MIDI file.

Load/Save Commands

General Information

File Formats

Asynchronous Handling

Path Handling

Examples

See Also

get_folder()

Example

See Also

load_array()

Remarks

Example

See Also

load_array_str()

Remarks

Example

load_ir_sample()

Remarks

Example

See Also

save_array()

Remarks

See Also

save_array_str()

Remarks

Example

See Also

save_midi_file()

Example

See Also

Search results