Instrument
General Information
Instrument Structure
An instrument in Kontakt contains of groups and zones as its basic building blocks. Contrary to Creator Tools, in Kontakt Lua API zones are not hierarchically tied to groups. Instead, they are accessed individually and directly by their own separate index. A zone contains a property which links it to one and only one group. See get_zone_group.
Additionally, an instrument in Kontakt also contains group triggering criteria, voice groups for managing polyphony, playback mode, MIDI input and audio output overrides, polyphonic effects and modulation.
Constants
cc64_modes
cc64_modes: table
“midi_exclusive”
“pedal_and_cc”
“pedal_exclusive”
instrument_purge_modes
instrument_purge_modes: table
“all_samples”
“reload_all_samples”
“reset_markers”
“update_sample_pool”
max_num_instrument_aux
max_num_instrument_aux: integer
As of Kontakt 7.5, this constant returns 4.
max_num_instruments
max_num_instruments: integer
As of Kontakt 7.5, this constant returns 64.
max_num_scripts
max_num_scripts: integer
As of Kontakt 7.5, this constant returns 5.
max_num_voice_groups
max_num_voice_groups: integer
As of Kontakt 7.5, this constant returns 128.
save_modes
save_modes: table
“monolith”
“patch”
“samples”
voice_stealing_modes
voice_stealing_modes: table
“any”
“highest”
“lowest”
“newest”
“oldest”
Get Property
get_free_instrument_index
get_free_instrument_index() -> integer?
Returns the next available instrument index (not occupied with an already loaded instrument).
get_instrument_aux_level
get_instrument_aux_level(instrument_idx: integer, aux_index: integer) -> float
Returns the specified aux send level of the specified instrument.
get_instrument_indices
get_instrument_indices() -> table
The returned table contains the indices of all instruments. Pass these indices to functions taking instrument_idx as an argument.
get_instrument_midi_channel
get_instrument_midi_channel(instrument_idx: integer) -> integer
Returns the MIDI channel of the specified instrument.
get_instrument_mute
get_instrument_mute(instrument_idx: integer) -> bool
Returns the mute state of the specified instrument.
get_instrument_name
get_instrument_name(instrument_idx: integer) -> string
Returns the name of the specified instrument.
get_instrument_options
get_instrument_options(instrument_idx: integer) -> table
Returns specified instrument’s options as a table with the following entries:
Instrument
key_switch: integer (default: nil)key_range_from: integer (default: 0)key_range_to: integer (default: 127)velocity_range_from: integer (default: 0)velocity_range_to: integer (default: 127)midi_transpose: integer (default: 0)wallpaper: string (default: nil)
Voice Handling
voice_stealing_mode: voice_stealing_modes (default: “oldest”)voice_stealing_fadeout: integer (default: 10)time_machine_voice_limit: integer (default: 8)time_machine_voice_limit_hq: integer (default: 4)time_machine_use_legacy: boolean (default: false)
DFD
dfd_buffersize: integer (default: 60)background_loading: boolean (default: true)
Controller
cc_64_mode: cc64_modes (default: “pedal_and_cc”)use_cc_120_123: boolean (default: true)use_cc_7_10: boolean (default: true)cc_7_range: integer (default: 0)
Snapshots
show_factory_snapshots: boolean (default: true)factory_snapshot_path: string (default: depends on instrument, or nil)user_snapshot_path: string (default: depends on instrument, or nil)
Info
info_icon: integer (default: 28)info: string (default: "(null)")info_author: string (default: “Kontakt”)info_url: string (default: “(null)”)
Individual entries of this table can be omitted. In that case the default value is used.
get_instrument_output_channel
get_instrument_output_channel(instrument_idx: integer) -> integer
Returns the audio output channel of the specified instrument.
get_instrument_pan
get_instrument_pan(instrument_idx: integer) -> float
Returns the output panorama of the specified instrument.
get_instrument_polyphony
get_instrument_polyphony(instrument_idx: integer) -> integer
Returns the maximum polyphony of the specified instrument.
get_instrument_script_linked_filename
get_instrument_script_linked_filename(instrument_idx: integer, script_idx: integer) -> string
Returns the filename of the script linked to the specified script slot in the specified instrument.
get_instrument_script_name
get_instrument_script_name(instrument_idx: integer, script_idx: integer) -> string
Returns the title of the script in the specified script slot in the specified instrument.
get_instrument_script_source
get_instrument_script_source(instrument_idx: integer, script_idx: integer) -> string
Returns the complete script contained in the specified script slot in the specified instrument.
get_instrument_solo
get_instrument_solo(instrument_idx: integer) -> bool
Returns the solo state of the specified instrument.
get_instrument_tune
get_instrument_tune(instrument_idx: integer) -> float
Returns the tuning of the specified instrument in semitones.
get_instrument_volume
get_instrument_volume(instrument_idx: integer) -> float
Returns the output volume of the specified instrument in dB.
get_voice_groups
get_voice_groups(instrument_idx: integer) -> table
Returns all voice groups of the specified instrument as a table with a maximum of 128 entries.
is_instrument_script_bypassed
is_instrument_script_bypassed(instrument_idx: integer, script_idx: integer) -> bool
Returns true if the specified script slot in the specified instrument is bypassed.
is_instrument_script_linked
is_instrument_script_linked(instrument_idx: integer, script_idx: integer) -> bool
Returns true if the script at the specified script slot of the specified instrument index is linked to a file in the resource container.
is_instrument_script_protected
is_instrument_script_protected(instrument_idx: integer, script_idx: integer) -> bool
Returns true if the specified script slot in the specified instrument is protected with a password.
Set Property
reset_instrument
reset_instrument(instrument_idx: integer)
Resets the whole instrument at the specified instrument index to the default state.
set_instrument_aux_level
set_instrument_aux_level(instrument_idx: integer, aux_index: integer, level: float)
Sets the level of the specified aux index for the specified instrument in dB. Range is -math.huge … 12.0.
set_instrument_midi_channel
set_instrument_midi_channel(instrument_idx: integer, channel: integer)
Sets the MIDI channel for the specified instrument. 0 is Omni, 1 … 64 is channels 1-16 across ports A-D.
set_instrument_mute
set_instrument_mute(instrument_idx: integer, value: bool)
Mutes the specified instrument.
set_instrument_name
set_instrument_name(instrument_idx: integer, name: string)
Sets the name of the specified instrument.
set_instrument_options
set_instrument_options(instrument_idx: integer, options: table)
Specified instrument’s options can be set by passing a table with one or more of the following entries:
Instrument
key_switch: integer (default: nil)key_range_from: integer (default: 0)key_range_to: integer (default: 127)velocity_range_from: integer (default: 0)velocity_range_to: integer (default: 127)midi_transpose: integer (default: 0)wallpaper: string (default: nil)
Voice Handling
voice_stealing_mode: voice_stealing_modes (default: “oldest”)voice_stealing_fadeout: integer (default: 10)time_machine_voice_limit: integer (default: 8)time_machine_voice_limit_hq: integer (default: 4)time_machine_use_legacy: boolean (default: false)
DFD
dfd_buffersize: integer (default: 60)background_loading: boolean (default: true)
Controller
cc_64_mode: cc64_modes (default: “pedal_and_cc”)use_cc_120_123: boolean (default: true)use_cc_7_10: boolean (default: true)cc_7_range: integer (default: 0)
Snapshots
show_factory_snapshots: boolean (default: true)factory_snapshot_path: string (default: depends on instrument, or nil)user_snapshot_path: string (default: depends on instrument, or nil)
Info
info_icon: integer (default: 28)info: string (default: “(null)”)info_author: string (default: “Kontakt”)info_url: string (default: “(null)”)
Individual entries of this table can be omitted. In that case the default value is used.
set_instrument_output_channel
set_instrument_output_channel(instrument_idx: integer, channel: integer)
Sets the audio output for the specified instrument. Make sure to check how many outputs are available before setting!
set_instrument_pan
set_instrument_pan(instrument_idx: integer, percent: float)
Sets the output panorama of the specified instrument. Range is -100.0 … 100.0.
set_instrument_polyphony
set_instrument_polyphony(instrument_idx: integer, voices: integer)
Sets the maximum polyphony for the specified instrument. Minimum value is 1.
set_instrument_script_bypassed
set_instrument_script_bypassed(instrument_idx: integer, script_idx: integer, bypass: bool)
Bypasses the specified script of the specified instrument.
set_instrument_script_linked_filename
set_instrument_script_linked_filename(instrument_idx: integer, script_idx: integer, filename: string)
Sets the filename of the script packed inside the resource container and linked to a script slot.
set_instrument_script_name
set_instrument_script_name(instrument_idx: integer, script_idx: integer, name: string)
Sets the name of the script (without extension). This will be displayed in the script slot header or the script tab if visible in performance view.
set_instrument_script_source
set_instrument_script_source(instrument_idx: integer, script_idx: integer, source: string)
Sets the script source by passing an absolute filepath as argument.
set_instrument_solo
set_instrument_solo(instrument_idx: integer, value: bool)
Soloes the specified instrument.
set_instrument_tune
set_instrument_tune(instrument_idx: integer, semitones: float)
Sets the output tuning of the specified instrument in semitones. Range is -36.0 … 36.0.
set_instrument_volume
set_instrument_volume(instrument_idx: integer, level: float)
Sets the output volume of the specified instrument in dB. Range is -math.huge … 12.0.
set_voice_groups
set_voice_groups(instrument_idx: integer, voice_groups: table)
Sets voice groups of the specified instrument as a table with a maximum of 128 entries, matching the total number of possible voice groups. Nil table entries will set voice group to default values. Voice group parameters are defined in a sub-table:
mode: voice_group_modes (default: “oldest”)name: string (default: ’’)voices: integer (default: 1)fade_time: integer (default: 10)prefer_released: boolean (default: true)exclusive_group: integer (default: nil)
Individual entries of this table can be omitted. In that case the default value is used.
Modifiers
add_instrument
add_instrument(instrument_idx: integer?) -> integer
Inserts a new instrument at given or next available instrument index. Returns the index of the new instrument. Pass this index to functions taking instrument_idx as an argument.
add_instrument_bank
add_instrument_bank(instrument_slot: integer?) -> integer
Inserts a new instrument bank at given or next available instrument slot. Returns the instrument slot of the new instrument bank.
remove_instrument
remove_instrument(instrument_idx: integer)
Removes the instrument at the specified instrument index from the multi.
remove_instrument_bank
remove_instrument_bank(instrument_slot: integer)
Removes the instrument bank at the specified instrument slot from the multi.
File I/O
load_instrument
load_instrument(filename: string, instrument_idx: integer?) -> integer
Loads an instrument to the specified slot index. If that slot is already occupied, next available slot is used. Returns the slot index of the new instrument. Note: contrary to most other functions, the slot index here can also refer to a slot within an instrument bank!
load_snapshot
load_snapshot(instrument_idx: integer, filename: string)
Loads the specified snapshot in the specified instrument index.
save_instrument
save_instrument(instrument_idx: integer, filename: string, options: table)
Save options can be defined by passing a table with one or more of the following entries:
mode: save_modes (default: “patch”)absolute_paths: boolean (default: false)compress_samples: boolean (default: false)samples_sub_dir: string
Individual entries of this table can be omitted. In that case the default value is used.
save_snapshot
save_snapshot(instrument_idx: integer, filename: string)
Saves the state of the instrument at the specified insturment index as a snapshot at the specified absolute path.