Introduction and Setup

Constants and functions in this reference document are described using the following conventions:

constant_name: constant_type

function_name(argument_name: argument_type, ...) -> return_type

Optional arguments or return values are marked by a question mark ?. If a table can be passed as an argument, or is returned by a function, its key-value pairs are described below the function.

Kontakt Lua API scripts can be executed either from Kontakt's user interface, or passed as a command line argument when running Kontakt from a command line.

In Kontakt's main menu the entry “Run Lua script…” (F11) opens a file select dialog. In order to run the same script again, press Ctrl+F11 (Cmd+F11 on macOS).

Lua scripts also show up in Kontakt's Files browser and can be executed by a double-click or by dragging and dropping a script onto the rack. Drag and drop is also possible from operating system’s file manager (Finder on macOS or Explorer on Windows).

Kontakt Lua API is designed to cooperate with Kontakt's rack and edit views. Running a script operates on the current state of Kontakt, without resetting it. This allows for utility scripts which can do specific tasks that can be cumbersome to do manually in the edit view. If you need to start with a clean state, simply call Kontakt.reset_multi(). The constants edit_instrument provide necessary information to retrieve the current context.

In order to start using Kontakt Lua API facilities, please enable Developer Options checkbox in Kontakt’s Options > Developer pane.

If a filename with the extension .lua is passed as an argument when opening Kontakt from the command line, the script is executed. The script output is directed to the terminal.

On both platforms, messages from Lua scripts will be visible in the terminal panel of the text editor if Kontakt was launched within the editor. KSP messages, warnings, script errors and variable watching will also be routed to this terminal. However, if Creator Tools is running, all messaging from Kontakt will be redirected to its debugger instead.

This is the recommended workflow. Follow the instructions below for your preferred text editor in order to set this up.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Kontakt 7",
      "type": "shell",
      "command": "\"/Applications/Native Instruments/Kontakt 7/Kontakt 7.app/Contents/macOS/Kontakt 7\"",
      "windows": {
        "command": "\"C:\\Program Files\\Native Instruments\\Kontakt 7\\Kontakt 7.exe\"",
        "options": {
          "shell": {
            "executable": "cmd.exe",
            "args": ["/d", "/c"]
          }
        }
      },
      "args": [],
      "problemMatcher": [],
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared",
        "showReuseMessage": true,
        "clear": true
      },
    }
  ]
}

{
  "shell_cmd": ["\"/Applications/Native Instruments/Kontakt 7/Kontakt 7.app/Contents/macOS/Kontakt 7\"", "$file"],
}

{
  "cmd": ["c:\\Program Files\\Native Instruments\\Kontakt 7\\Kontakt 7.exe", "$file"],
}