Skip to main content
  • KSP Reference Manual
  • Load/Save Commands

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. 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().

See Also

on async_complete

General: $NI_ASYNC_ID, $NI_ASYNC_EXIT_STATUS

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 following:

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

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

$GET_FOLDER_FACTORY_DIR

The factory 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.

Remarks

  • The behaviour of $GET_FOLDER_LIBRARY_DIR changed from KONTAKT 5 onwards. If the NKI belongs to an encoded library, it will point to its library folder. Otherwise, the user content directory is returned.

Example

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

Displaying the path of the factory folder of KONTAKT

See Also 

load_ir_sample()

General: $GET_FOLDER_LIBRARY_DIR, $GET_FOLDER_FACTORY_DIR, $GET_FOLDER_PATCH_DIR

load_array()

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

Loads an array from an external .nka file

<array-variable>

The name of the array variable, this 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. Can only be used in UI, PGS and persistence_changed callbacks.

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>\

Can be used in init (synchronous), UI, PGS, and persistence_changed (asynchronous) callbacks.

2: The array is directly loaded from the "Data" folder inside the resource container. Can be used in init (synchronous), UI, PGS, and persistence_changed (asynchronous) callbacks.

Remarks

  • It is also possible to load string arrays from .nka files.

  • It is not possible to load an array with %xyz in its .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 init callback, please remember that the loaded data will be overwritten at the end of the callback if the array is persistent. 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 will not know the file has ended and will continue to try and load other data from the resources container. Files generated by the save_array() command have this automatically, but if you are creating files manually, 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

See Also 

on async_complete

save_array()

General: $NI_ASYNC_ID, $NI_ASYNC_EXIT_STATUS

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.

  • Can be used in on init (synchronous), persistence_changed, UI and PGS (asynchronous) callbacks.

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(<file-path>, <slot>, <generic>)

Loads an impulse response sample into KONTAKT's convolution effect

<file-path>

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 subfolders inside the "ir_samples" folder 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

See Also

get_folder()

on async_complete

General: $NI_ASYNC_ID

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. Can only be used in UI and PGS callbacks.

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:

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

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

Can be used in UI, PGS, and persistence_changed callbacks.

Remarks

  • It is also possible to save string arrays into .nka files. Real arrays are not supported.

  • 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.

See Also

on async_complete

load_array()

General: $NI_ASYNC_ID, $NI_ASYNC_EXIT_STATUS

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.

  • Can be used in persistence_changed, UI and PGS 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.

See Also

save_array()

load_array_str()

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 file

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

See Also

mf_insert_file()

mf_set_export_area()