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
General: $NI_ASYNC_ID
, $NI_ASYNC_EXIT_STATUS
get_folder()
| |
---|---|
Returns the path specified with the built-in path variable | |
| The following path variables are available:
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: Windows:
The factory folder of KONTAKT, mainly used for loading factory IR samples. Note: this is not the KONTAKT Factory Library folder!
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
General: $GET_FOLDER_LIBRARY_DIR
, $GET_FOLDER_FACTORY_DIR
, $GET_FOLDER_PATCH_DIR
load_array()
| |
---|---|
Loads an array from an external .nka file | |
| The name of the array variable, this must be present as the first line of the .nka file |
| 0: A dialog window pops up, allowing you to select an .nka file to load. Can only be used in UI, PGS and 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: Windows: Can be used in init (synchronous), UI, PGS, and 2: The array is directly loaded from the "Data" folder inside the resource container. Can be used in init (synchronous), UI, PGS, and |
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 insideon 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
General: $NI_ASYNC_ID
, $NI_ASYNC_EXIT_STATUS
load_array_str()
| |
---|---|
Loads an array from an external .nka file, using an absolute path to the file | |
| The name of the array variable, this must be present as the first line of the .nka file |
| 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()
| |
---|---|
Loads an impulse response sample into KONTAKT's convolution effect | |
| 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: Windows: |
| The slot index of the convolution effect (zero-based) |
| 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:
|
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
General: $NI_ASYNC_ID
save_array()
| |
---|---|
Saves an array to an external .nka file | |
| The name of the array variable to be saved |
| 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: Win: Can be used in UI, PGS, and |
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
General: $NI_ASYNC_ID
, $NI_ASYNC_EXIT_STATUS
save_array_str()
| |
---|---|
Saves an array to an external .nka file with the specified absolute path | |
| The name of the array variable to be saved |
| 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_midi_file()
| |
---|---|
Saves a MIDI file with the range specified by the | |
| 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