Skip to main content

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

  • IR samples (.wav, .aif, .aiff, .ncw) to be used with KONTAKT's convolution effect (loading only)

Async 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 has to start with a slash character “/”. 

Examples

Factory folder on OS X:

/Library/Application Support/Native Instruments/Kontakt/

Factory folder on Windows:

/C:/Program Files/Common Files/Native Instruments/Kontakt/

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 belonging to an encoded library: library folder.

If used with an unencoded NKI: the user content directory.

$GET_FOLDER_FACTORY_DIR

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

Note: this is not the factory library folder!

$GET_FOLDER_PATCH_DIR

The directory in which the patch was saved.

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

Remarks

  • The behaviour $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 file (.nka file)

<array-variable>

The array variable, this name must be present in the .nka file

<mode>

0: A dialog window pops up, allowing you to select an .nka file. 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 library instruments, the "Data" folder is located here:

OS X: <UserName>/Library/Application Support/<Library Name>/

Win: C:\User\<UserName>\AppData\Local\<Library Name>\

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

2: The array is directly loaded from the "data" folder inside the resource container. Can be used in UI, PGS, init (synchronous) and persistence_changed 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 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 within an init callback.

  • When using mode 0 the callback continues even if the loading dialog is still open.

  • Mode 2 is only available for loading arrays, i.e. save_array() does not have this option.

  • 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, then 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, then this is something to take care of.

Example

on init
	declare $count
	declare ui_button $Load
	declare ui_button $Save
	declare ui_table %table[8] (2,2,100)
	make_persistent(%table)
	declare %preset[8]
	declare $load_arr_id
	$load_arr_id := -1
	declare $save_arr_id
	$save_arr_id := -1
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 file (.nka file) using the file's absolute path

<array-variable>

The array variable. This name must be present in 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 init (synchronous), persistence_changed, UI and PGS callbacks.

Example

on init
	set_ui_height(2)
	
	declare @basepath_browser
	{set browser path here, for example
	@basepath_browser := "/Users/<username>/Desktop/Arrays"}
	
	declare @file_path
	make_persistent(@file_path)
	
	declare @file_name
	make_persistent(@file_name)
	
	declare ui_file_selector $file_browser
	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)
	move_control_px($file_browser,66,2)
	
	declare ui_table %table[8] (2,2,100)
	make_persistent(%table)
	move_control(%table,3,1)
	
	declare %preset[8]
	
	declare $load_arr_id
	$load_arr_id := -1
	declare $count
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 < 8)
				%table[$count] := %preset[$count]
				inc($count)
			end while
		end if
	end if
end on

on ui_control ($file_browser)
	@file_name := fs_get_filename($browser_id,0)
	@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:

OS X: /Users/<username>/Documents/Native Instruments/Kontakt/

Windows: C:/Users/<username>/Documents/Native Instruments/Kontakt/

<slot>

The slot index of the convolution effect (zero-based)

<generic>

Specifies whether the convolution effect is used as an:

1: Insert Effect

0: Send 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 are being ignored during the creation of a Resource Container monolith.

Example

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

on ui_control ($Load)
	$load_ir_id := load_ir_sample("Small Ambience.wav",0,0)
	$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 send effect in the first slot

See Also

get_folder()

on async_complete

General: $NI_ASYNC_ID

save_array()

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

Saves an array to an external file, i.e. an .nka file

<array-variable>

The array 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 library instruments, the "Data" folder is located here:

OS X: <UserName>/Library/Application Support/<Library Name>/

Win: C:\User\<UserName>\AppData\Local\<Library Name>\

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

Remarks

  • It is also possible to save string arrays into .nka files.

  • The exported .nka file consists of the name of the array followed its values.

  • 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 file, i.e. an .nka file, using the specified absolute path

<array-variable>

The array 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
	declare $count
	
	declare @path
	{set save path here, for example
	@path := "/Users/<username>/Desktop/Arrays/"}
	
	declare ui_button $Save
	
	declare ui_table %table[8] (2,2,100)
	make_persistent(%table)
	
	declare %preset[8]
	
	declare $save_arr_id
	$save_arr_id := -1
	
	declare ui_text_edit @preset_name
	make_persistent(@preset_name)
	
	set_control_par_str(get_ui_id(@preset_name),$CONTROL_PAR_TEXT,"empty")
	set_control_par(get_ui_id(@preset_name),$CONTROL_PAR_FONT_TYPE,25)
	set_control_par(get_ui_id(@preset_name),$CONTROL_PAR_POS_X,73 + 3*92)
	set_control_par(get_ui_id(@preset_name),$CONTROL_PAR_POS_Y,2)
	
	declare ui_label $pattern_lbl(1,1)
	set_text($pattern_lbl,"")
	move_control_px($pattern_lbl,66 + 3*92,2)
	
end on

on ui_control (%table)
	$count := 0
	while($count < 8)
		%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 file with a range specified by the mf_set_export_area() command.

<path>

The absolute path of the file

Example

on init
	declare @path
	{set save path here, for example
	@path := "/Users/<username>/Desktop/MIDI Files/"}
	
	declare ui_text_edit @file_name
	set_control_par_str(get_ui_id(@file_name),$CONTROL_PAR_TEXT,"<empty>")
	set_control_par(get_ui_id(@file_name),$CONTROL_PAR_FONT_TYPE,25)
	make_persistent(@file_name)
	move_control_px(@file_name,73,2)
	
	declare ui_label $file_name_lbl(1,1)
	set_text($file_name_lbl,"")
	move_control_px($file_name_lbl,66,2)
	
	declare ui_button $Save
	move_control($Save,2,1)
	
	declare $save_mf_id
	$save_mf_id := -1
	
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()