Native Instruments Creator Tools

https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en
Admin
A suite of tools developed to support the creation of KONTAKT instruments with features including...
Tokens:13,046
Snippets:151
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Initialize and Load Performance View in KSP

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/overview-of-creator-tools

Example script to load a performance view when the Kontakt instrument is initialized.

```ksp
on init
load_performance_view ("filename")
end on
```

--------------------------------

### Create and Add UI Elements to a Panel in KSP

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/overview-of-creator-tools

Example demonstrating how to declare a panel, a knob, and then add the knob to the panel.

```ksp
declare ui_panel $mixer
declare ui_knob $volume (0, 300, 1)
set_control_par(get_ui_id($volume), $CONTROL_PAR_PARENT_PANEL, get_ui_id($mixer))
```

--------------------------------

### Find Loop Points for Samples

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Use the `findLoop()` MIR function to analyze samples and suggest loop points. The function returns loop start and end variables that can be used to set loop points for a zone. All arguments except `filePath` are optional; if only the path is provided, the algorithm calculates the remaining arguments.

```lua
local loop_start, loop_end = mir.findLoop(file)
local loop_length = loop_end - loop_start
z.loops[0].start = loop_start
z.loops[0].length = loop_length

```

--------------------------------

### Detect Pitch of a Single Sample

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Use this function to get the fundamental frequency of a monophonic audio sample. It returns a float representing the MIDI pitch value or a specific invalid constant if detection fails.

```lua
pitchVal = mir.detectPitch('fullPathToSample')
```

--------------------------------

### Get Number of Elements in Container

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

Use the Lua length operator (#) to get the number of elements in a container like instrument.groups. Vectors are zero-indexed.

```lua
print(#instrument.groups)
```

--------------------------------

### Working with Containers

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

Illustrates how to create new container objects and perform structural changes like adding or inserting elements.

```APIDOC
## Working with containers

```lua
Group()
```

_Creates a new object of type Group._

```lua
print(scriptPath)
```

_Prints the directory of the running script._

Structural changes like add, remove, insert are possible:

```lua
instrument.groups:add(Group())
```

_Adds a new empty group at the end._

```lua
instrument.groups:insert(0, instrument.groups[3])
```

_Inserts a deep copy of the 4th group at index 0 i.e. at the beginning._
```

--------------------------------

### Write Text to a File with Lua

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/overview-of-creator-tools

This Lua script demonstrates how to write text to a file. It uses `scriptPath` and `filesystem.preferred` to construct a platform-independent file path.

```Lua
local some_text = "best text ever"
local some_file = scriptPath .. filesystem.preferred("/some_file.txt")

file = io.open(some_file,"w")
file:write(some_text)
io.close(file)
```

--------------------------------

### Detect Loudness Values of Samples in a Folder with Optional Frame and Hop Sizes

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes all audio samples in a directory to compute their loudness values in dB. Optional frame size and hop size parameters are available, with defaults of 0.4 and 0.1 seconds. Failed detections will result in the kDetectLoudnessInvalid constant.

```lua
mir.detectLoudnessBatch(‘fullPathToFolder’, frameSizeInSeconds, hopSizeInSeconds)
```

--------------------------------

### Detect Sample Types for Audio Samples in Folder

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes audio samples in the specified directory and stores the resulting sample types in a Lua table.

```lua
sampleTypeBatchData = mir.detectSampleTypeBatch(‘fullPathToFolder’)
```

--------------------------------

### Accessing Instrument Properties

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

Demonstrates how to access and print properties of a connected instrument using the global 'instrument' variable. Ensure an instrument is loaded for these commands to return meaningful data.

```lua
print(instrument)
```

```lua
print(instrument.groups[0].name)
```

```lua
print(instrument.groups[0].zones[0].keyRange.high)
```

--------------------------------

### Detect RMS Values of Samples in a Folder with Optional Frame and Hop Sizes

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Processes all audio samples in a directory to calculate their RMS values in dB. Optional frame size and hop size parameters can be specified; defaults are 0.4 and 0.1 seconds. Returns kDetectRMSInvalid for any failed detections.

```lua
mir.detectRMSBatch(‘fullPathToFolder’, frameSizeInSeconds, hopSizeInSeconds)
```

--------------------------------

### Iterating Over Containers

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

Demonstrates how to iterate through containers such as groups or zones using their indices and access their properties.

```APIDOC
## Iterate over containers

The brackets [ ] refer to the nth element of the group or zone vector. The number of elements can be read with Lua‘s length operator:

```lua
print(#instrument.groups)
```

This allows iterating through groups or zones:

```lua
for n=0,#instrument.groups-1 do
    print(instrument.groups[n].name)
end
```

Note that vectors are zero-indexed! There are other ways to iterate over containers without using indices. In the Binding Reference chapter, iteration via pairs is described for Vector and Struct and iteration via the traverse function is described under Algorithms.
```

--------------------------------

### Load Performance View in KSP

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/overview-of-creator-tools

Loads a performance view file into the NKI. The file must be located in the \"_performance_view_\" subfolder.

```ksp
load_performance_view("filename")
```

--------------------------------

### Detect Peak Values of Samples in a Folder

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes all audio samples in a directory to determine their peak values in dB. The results are returned in a Lua table where keys are sample paths. Failed detections will yield the kDetectPeakInvalid constant.

```lua
mir.detectPeakBatch('fullPathToFolder')
```

--------------------------------

### Algorithms

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Provides free functions that operate on any type, including path manipulation, JSON conversion, and object traversal.

```APIDOC
## Algorithms
The following are free functions operating on any **Type**.
`path(object)`| Returns the path to object  
---|---
`resolve(path)`| Returns the object at path or nil  
`traverse(object, function(key, object, [level]))`| Recursively traverses object and calls function where key is the index or field name of the object in parent  
`string = json(object, [indent])`| Converts objects to a json string and returns it  
`object = json(type, string)`| Converts the string to an object of type and returns it
```

--------------------------------

### List Directory Contents

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Iterates through and prints the paths of files and subdirectories within a given directory.

```lua
for _,p in filesystem.directory(path) do
    print(p)
end

```

--------------------------------

### File System Operations

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Functions for interacting with the file system, based on the boost filesystem library. Supports directory listing, path manipulation, and file queries.

```APIDOC
## File system
The Lua binding is based on the C++ library boost filesystem. In contrary to the original C++ design, the Lua binding does not define an abstraction for path. Instead, path always refers to a Lua string.
The following chapter lists functions from the aforementioned library and the associated data type they return. For a detailed description of each function, please refer to the reference documentation.
#### Examples
```
for _,p in filesystem.directory(path) do
    print(p)
end

```
 __
_Lists paths in directory_
```
for _,p in filesystem.directoryRecursive(path) do
    print(p)
end
```
 __
_Lists paths in directory and all sub-directories_
#### Functions
Note that all functions live in the global filesystem.
Iterators  
---
**Function**| **Returned data type**  
`filesystem.directory(path)`| `iterator`  
`filesystem.directoryRecursive(path)`| `iterator`  
Path  
---
These functions return a string which contains the modified path.  
`filesystem.native(path)`| `string`  
`filesystem.rootName(path)`| `string`  
`filesystem.rootDirectory(path)`| `string`  
`filesystem.rootPath(path)`| `string`  
`filesystem.relativePath(path)`| `string`  
`filesystem.parentPath(path)`| `string`  
`filesystem.filename(path)`| `string`  
`filesystem.stem(path)`| `string`  
`filesystem.replaceExtension(path, newExtension)`| `string`  
`filesystem.extension(path)`| `string`  
`filesystem.preferred(path)`| `string`  
Query  
---
These functions query a given path.  
`filesystem.empty(path)`| `bool`  
`filesystem.isDot(path)`| `bool`  
`filesystem.isDotDot(path)`| `bool`  
`filesystem.hasRootPath(path)`| `bool`  
`filesystem.hasRootName(path)`| `bool`  
`filesystem.hasRootDirectory(path)`| `bool`  
`filesystem.hasRelativePath(path)`| `bool`  
`filesystem.hasParentPath(path)`| `bool`  
`filesystem.hasFilename(path)`| `bool`  
`filesystem.hasStem(path)`| `bool`  
`filesystem.hasExtension(path)`| `bool`  
`filesystem.isAbsolute(path)`| `bool`  
`filesystem.isRelative(path)`| `bool`  
Operational  
---
These functions allow queries on the underlying filesystem.  
**Path**  
`filesystem.exists(path)`| `bool`  
`filesystem.equivalent(path1, path2)`| `bool`  
`filesystem.fileSize(path)`| `int`  
`filesystem.currentPath()`| `string`  
`filesystem.initialPath()`| `string`  
`filesystem.absolute(path, [base])`| `string`  
`filesystem.canonical(path, [base])`| `string`  
`filesystem.systemComplete(path)`| `string`  
**Test**  
`filesystem.isDirectory(path)`| `bool`  
`filesystem.isEmpty(path)`| `bool`  
`filesystem.isRegularFile(path)`| `bool`  
`filesystem.isSymLink(path)`| `bool`  
`filesystem.isOther(path)`| `bool`  
Last Write Time  
---
`filesystem.lastWriteTime(path)`| `int`  
Links  
---
`filesystem.readSymLink(path)`5| `string`  
`filesystem.hardLinkCount(path)`| `int`  
For convenience users can declare `fs = filesystem` and call all filesystem functions using the fs prefix, demonstrated in the following example. 
```
fs = filesystem
iterator fs.directory(path)
iterator fs.directoryRecursive(path)
```
__
```

--------------------------------

### Vector Type

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Explains the constructors, operators, properties, and functions for vector objects.

```APIDOC
## Vector

Type-safe, dynamically sized, zero-indexed, random access container.

### Constructors

- `vector()`: Returns a new vector.
- `vector(other)`: Returns a copy of the other vector.
- `vector(size)`: Returns a new vector with size elements.
- `vector(args)`: Returns a new vector initialized with variadic args.

### Operators

- `#`: Returns the number of elements i.e. the size of the vector.
- `pairs`: Returns an iterator function for iterating over all elements.
- `value/object = vector[index]`: Returns the value if vector type is scalar, otherwise returns the object.
- `vector[index] = value`: Sets value at index.
- `vector[index] = object`: Assigns object to index.

### Properties

- `vector.type`: Returns the vector type.
- `vector.empty`: Returns true if the vector has no elements.
- `vector.initial`: Returns true if the vector is in its initial state.

### Functions

- `vector:set(index, object)`: Sets element at index to object.
- `vector:get(index)`: Returns object at index.
- `vector:reset()`: Resets the vector to initial.
- `vector:resize(size)`: Resizes the vector to size elements.
- `vector:resolve(path)`: Returns the object at path or nil.
- `vector:assign(other)`: Assigns a copy of the other vector.
- `vector:add(object)`: Inserts object at the end.
- `vector:add(value)`: Inserts value at the end.
- `vector:insert(index, object)`: Inserts object before index.
- `vector:insert(index, value)`: Inserts value before index.
- `vector:remove(index)`: Removes element at index.
```

--------------------------------

### Struct Type

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Details the constructors, operators, properties, and functions for struct objects.

```APIDOC
## Struct

Type-safe record with named fields.

### Constructors

- `struct()`: Returns a new struct.
- `struct(other)`: Returns a copy of the other struct.

### Operators

- `#`: Returns the number of used fields.
- `pairs`: Returns an iterator function for iterating over used fields.
- `value/object = struct.field`: Returns the value if field contains a scalar, otherwise returns the object.
- `struct.field = value`: Sets element value of field.
- `struct.field = object`: Assigns object to field.

### Properties

- `Struct.type`: Returns the struct type.
- `struct.empty`: Returns true if the struct has no used fields.
- `struct.initial`: Returns true if the struct is in its initial state.

### Functions

- `struct:set(index, object)`: Assigns object at index.
- `struct:get(index)`: Returns object at index.
- `struct:reset()`: Resets the struct to its initial state.
- `struct:reset(index)`: Resets the field at index.
- `struct:reset(field)`: Resets the field.
- `struct:used(field)`: Returns true if the field is used.
- `struct:resolve(path)`: Returns the object at path.
- `struct:assign(other)`: Assigns a copy of the other struct.
```

--------------------------------

### Detect RMS Values for Audio Samples in Folder

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes all audio samples in the specified directory with custom frame and hop sizes, storing the resulting RMS values.

```lua
rmsBatchData = mir.detectRMSBatch(‘fullPathToFolder', 0.02, 0.01)
```

--------------------------------

### Detect Loudness Value of a Single Sample with Optional Frame and Hop Sizes

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Determines the loudness value in dB for an audio sample. Frame size and hop size can be optionally set, defaulting to 0.4 and 0.1 seconds respectively. Returns kDetectLoudnessInvalid if detection fails.

```lua
mir.detectLoudness('fullPathToSample', frameSizeInSeconds, hopSizeInSeconds)
```

--------------------------------

### List Directory Contents Recursively

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Iterates through and prints the paths of files and subdirectories within a given directory and all its subdirectories.

```lua
for _,p in filesystem.directoryRecursive(path) do
    print(p)
end
```

--------------------------------

### Print Directory Structure with Lua

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/overview-of-creator-tools

This Lua script prints the directory structure to the console. It dynamically determines the correct command ('dir' or 'ls') based on the operating system's path separator.

```Lua
local path_sep = package.config:sub(1,1)
local terminal_command
if path_sep == "\\" then
    terminal_command = "dir"
else
    terminal_command = "ls"
end
f = assert (io.popen(terminal_command))
for line in f:lines() do
    print(line)
end
f:close()
```

--------------------------------

### Alias Filesystem Functions

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Creates a shorthand alias 'fs' for the 'filesystem' table to simplify function calls.

```lua
fs = filesystem
iterator fs.directory(path)
iterator fs.directoryRecursive(path)
```

--------------------------------

### Print Instrument Variable

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

Prints the 'Instrument' object to the console if an instrument is connected, otherwise prints 'nil'.

```lua
print(instrument)
```

--------------------------------

### Changing Properties

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

Shows how to modify properties of elements within containers, both individually and within a loop.

```APIDOC
## Changing properties

Changing values works naturally:

```lua
instrument.groups[0].name = "Release"
```

or in a loop:

```lua
for n=0,#instrument.groups-1 do
    instrument.groups[n].name = 'grp_'..n
end
```
```

--------------------------------

### Detect Sample Type of Audio Sample

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes an audio sample at the specified absolute file path and stores the resulting sample type category.

```lua
sampleType = mir.detectSampleType('fullPathToSample')
```

--------------------------------

### Declare a UI Panel in KSP

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/overview-of-creator-tools

Use this command to declare a panel in KSP. Panels can be used outside the GUI Designer.

```ksp
declare ui_panel $<my_panel_name>
```

--------------------------------

### Detect Pitch of Samples in a Folder

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

This function processes all audio samples within a specified folder to detect their fundamental frequencies. The results are stored in a Lua table, keyed by sample path. Invalid detections are represented by a specific constant.

```lua
pitchBatchData = mir.detectPitchBatch('fullPathToFolder')
pitchValue = pitchBatchData['fullPathToSample']
```

--------------------------------

### Instrument Structure Overview

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

This outlines the nested structure of a Kontakt instrument, detailing properties, types, and value ranges for elements like groups, zones, and loops. It serves as a reference for understanding the instrument's hierarchy.

```plaintext
Instrument                                     -- Struct
    name                                       -- String
    script                                     -- Struct
        name                                   -- String
        linked                                 -- Bool
        sourceCode                             -- String
        linkedFileName                         -- String
        bypass                                 -- Bool
    groups                                     -- Vector of Group
        name                                   -- String
        playbackMode                           -- Enum (see below)
        volume                                 -- Real, -inf..12
        pan                                    -- Real, -100..100
        tune                                   -- Real, -36..36
        zones                                  -- Vector of Zone
            file                               -- String
            volume                             -- Real, -inf..12
            pan                                -- Real, -100..100
            tune                               -- Real, -36..36
            rootKey                            -- Int, 0..127
            keyRange                           -- Struct
                low                            -- Int, 0..127
                high                           -- Int, 0..127
            velocityRange                      -- Struct
                low                            -- Int, 0..127
                high                           -- Int, 0..127
            sampleStart                        -- Int, 0..inf
            sampleStartModRange                -- Int, 0..inf
            sampleEnd                          -- Int, 4..inf
            loops                              -- Vector of Loop
                mode                           -- Int, 0..4 (see below)
                start                          -- Int, 0..inf
                length                         -- Int, 4..inf
                xfade                          -- Int, 0..1000000
                count                          -- Int, 0..1000000
                tune                           -- Real, -12..12
            grid                               -- Vector of Gridmode  
                mode                           -- Enum (see below)     
                bpm                            -- Real, 0.10..400
```

--------------------------------

### Add UI Control to a Panel in KSP

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/overview-of-creator-tools

Use this command to add a UI control or panel to an existing panel. Requires the UI ID of the control and the panel.

```ksp
set_control_par(<control-to-add-ui-ID>,$CONTROL_PAR_PARENT_PANEL,<panel-ui-ID>)
```

--------------------------------

### Create New Group Object

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

Instantiate a new object of type Group using the Group() constructor. This creates a new, empty group that can be further manipulated or added to containers.

```lua
Group()
```

--------------------------------

### Detect Instrument Type of Audio Sample

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes an audio sample at the specified absolute file path and stores the resulting instrument type category.

```lua
instType = mir.detectInstrumentType('fullPathToSample')
```

--------------------------------

### Sample Type Batch Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Processes a batch of audio samples to determine their types.

```APIDOC
## detectSampleTypeBatch

### Description
Processes a batch of audio samples in the folder specified by the 'fullPathToFolder' absolute path. Returns a Lua table with samplePath as the key and the respective sample type as the value. The returned types are the same as in the single function call above.

### Method Signature
`mir.detectSampleTypeBatch(‘fullPathToFolder’)`

### Parameters
- **fullPathToFolder** (string) - Required - The absolute path to the folder containing audio samples.
```

--------------------------------

### Access Group Name

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

Accesses and prints the name of the first group in the instrument. This will produce an error if no instrument is connected.

```lua
print(instrument.groups[0].name)
```

--------------------------------

### Detect RMS Value of a Single Sample with Optional Frame and Hop Sizes

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Calculates the RMS value in dB for an audio sample. Optional frame size and hop size parameters can be provided; otherwise, default values of 0.4 and 0.1 seconds are used respectively. Returns kDetectRMSInvalid on failure.

```lua
mir.detectRMS('fullPathToSample',frameSizeInSeconds, hopSizeInSeconds)
```

--------------------------------

### Detect Drum Type of Audio Sample

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes an audio sample at the specified absolute file path and stores the resulting drum type category.

```lua
drumType = mir.detectDrumType('fullPathToSample')
```

--------------------------------

### PosixTime Functions

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Utility functions for handling POSIX time, primarily for converting POSIX time integers to ISO formatted strings.

```APIDOC
## PosixTime
Date and time related utility functions.
Functions  
---
`string posixTime.toString(int)`| Converts the posix-time to an ISO string  
### Note
Note that all functions live in the global table posixTime.
#### Example
```
print(posixTime.toString(filesystem.lastWriteTime(...)))
```
 __
_Converts filesystem lastWriteTime to a string._
```

--------------------------------

### Instrument Structure Overview

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

This outlines the hierarchical structure of a Kontakt instrument, detailing properties, types, and value ranges for containers like groups and zones.

```plaintext
Instrument                                     -- Struct
    name                                       -- String
    script                                     -- Struct
        name                                   -- String
        linked                                 -- Bool
        sourceCode                             -- String
        linkedFileName                         -- String
        bypass                                 -- Bool
    groups                                     -- Vector of Group
        name                                   -- String
        playbackMode                           -- Enum (see below)
        volume                                 -- Real, -inf..12
        pan                                    -- Real, -100..100
        tune                                   -- Real, -36..36
        zones                                  -- Vector of Zone
            file                               -- String
            volume                             -- Real, -inf..12
            pan                                -- Real, -100..100
            tune                               -- Real, -36..36
            rootKey                            -- Int, 0..127
            keyRange                           -- Struct
                low                            -- Int, 0..127
                high                           -- Int, 0..127
            velocityRange                      -- Struct
                low                            -- Int, 0..127
                high                           -- Int, 0..127
            sampleStart                        -- Int, 0..inf
            sampleStartModRange                -- Int, 0..inf
            sampleEnd                          -- Int, 4..inf
            loops                              -- Vector of Loop
                mode                           -- Int, 0..4 (see below)
                start                          -- Int, 0..inf
                length                         -- Int, 4..inf
                xfade                          -- Int, 0..1000000
                count                          -- Int, 0..1000000
                tune                           -- Real, -12..12
            grid                               -- Vector of Gridmode  
                mode                           -- Enum (see below)     
                bpm                            -- Real, 0.10..400
                   

```

--------------------------------

### Detect Peak Value of a Single Sample

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Retrieves the peak value in dB for a given audio sample. If the detection fails, it returns the kDetectPeakInvalid constant.

```lua
mir.detectPeak('fullPathToSample')
```

--------------------------------

### Instrument Type Batch Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Processes a batch of audio samples to determine their specific instrument types.

```APIDOC
## detectInstrumentTypeBatch

### Description
Processes a batch of audio samples in the folder specified by the 'fullPathToFolder' absolute path. Returns a Lua table with samplePath as the key and the respective instrument type as the value. The returned types are the same as in the single function call above.

### Method Signature
`mir.detectInstrumentTypeBatch(‘fullPathToFolder’)`

### Parameters
- **fullPathToFolder** (string) - Required - The absolute path to the folder containing audio samples.
```

--------------------------------

### Base Type Accessors

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Describes the operators, properties, and functions available for base object types.

```APIDOC
## Base Type

### Operators

- `tostring`: Returns a string representation describing the object.

### Properties

- `object.typeinfo`: Returns type information as a string in the form Type‘Tag.
- `object.parent`: Returns the parent object or nil.

### Functions

- `object:equals(other)`: Returns true if object value is equal to the value of other.
- `object:instanceOf(type)`: Returns true if object is an instance of type i.e. `object.type == type`.
- `object:instanceOf(name)`: Returns true if object is an instance of a type named name i.e. `object.type.name = name`.
- `object:childOf(other)`: Returns true if object is a direct child of other i.e. `object.parent == other`.
- `object:childOf(type)`: Returns true if object is a direct child of an object of type i.e. `object.parent` and `object.parent.type == type`.
- `object:childOf(name)`: Returns true if object is a direct child of an object of a type named name i.e. `object.parent` and `object.parent.type.name == name`.
```

--------------------------------

### Detect Peak Value of Audio Sample

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes an audio sample at the specified absolute file path and stores the resulting Peak value.

```lua
peakVal = mir.detectPeak('fullPathToSample')
```

--------------------------------

### Accessing Script Path

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

Prints the directory path of the currently executing script using the global 'scriptPath' variable. This is useful for file I/O operations within scripts.

```lua
print(scriptPath)
```

--------------------------------

### Pitch Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Detects the fundamental frequency (MIDI pitch) of an audio sample. It can process a single file or a batch of files in a folder.

```APIDOC
## Pitch Detection

### Description
Detects the fundamental frequency of a monophonic/single note sample. The output corresponds to the MIDI scale (69 = 440 Hz) and ranges from semitone 15 (~20Hz) to semitone 120 (~8.4 kHz).

### Functions

`mir.detectPitch('fullPathToSample')`

Returns a floating point number corresponding to the MIDI pitch value of the audio sample specified in the 'fullPathToSample' absolute file path. If detection fails it will return `kDetectPitchInvalid`.

`mir.detectPitchBatch('fullPathToFolder')`

Returns a Lua table with samplePath as the table key and a floating point number corresponding to the detected pitch as the value. If detection fails it will return `kDetectPitchInvalid`.

### Examples

```lua
pitchVal = mir.detectPitch('fullPathToSample')
-- Sets pitchVal to the pitch of the sample at the 'fullPathToSample' filepath.

pitchBatchData = mir.detectPitchBatch('fullPathToFolder')
pitchValue = pitchBatchData['fullPathToSample']
-- Detects pitch of the samples in the 'fullPathToFolder' directory and stores them in the Lua table pitchBatchData. It then accesses pitchBatchData via the key 'fullPathToSample' and stores the resulting value in pitchValue.
```
```

--------------------------------

### RMS Batch Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes multiple audio samples in a folder to calculate their RMS values.

```APIDOC
## detectRMSBatch

### Description
Analyses all audio samples in the 'fullPathToFolder' directory and stores the resulting RMS values in a Lua table. Frame and Hop sizes can be specified for the calculation.

### Method Signature
`mir.detectRMSBatch(‘fullPathToFolder', frameSize, hopSize)`

### Parameters
- **fullPathToFolder** (string) - Required - The absolute path to the folder containing audio samples.
- **frameSize** (number) - Required - The frame size for RMS calculation.
- **hopSize** (number) - Required - The hop size for RMS calculation.
```

--------------------------------

### Drum Type Batch Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Processes a batch of audio samples to determine their specific drum types.

```APIDOC
## detectDrumTypeBatch

### Description
Processes a batch of audio samples in the folder specified by the 'fullPathToFolder' absolute path. Returns a Lua table with samplePath as the key and the respective drum type as the value. The returned types are the same as in the single function call above.

### Method Signature
`mir.detectDrumTypeBatch(‘fullPathToFolder’)`

### Parameters
- **fullPathToFolder** (string) - Required - The absolute path to the folder containing audio samples.
```

--------------------------------

### Peak Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Analyzes an audio sample to detect its peak value.

```APIDOC
## detectPeak

### Description
Analyses an audio sample at the 'fullPathToSample' absolute file path and stores the resulting Peak value.

### Method Signature
`mir.detectPeak('fullPathToSample')`

### Parameters
- **fullPathToSample** (string) - Required - The absolute file path to the audio sample.
```

--------------------------------

### Sample Type Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Determines the type of a single audio sample (Instrument, Drum, or Invalid).

```APIDOC
## detectSampleType

### Description
Returns the sample type of an audio sample at the 'fullPathToSample' absolute file path. Can return one of the following types: `DetectSampleType.INVALID`, `DetectSampleType.INSTRUMENT`, `DetectSampleType.DRUM`.

### Method Signature
`mir.detectSampleType('fullPathToSample')`

### Parameters
- **fullPathToSample** (string) - Required - The absolute file path to the audio sample.
```

--------------------------------

### Instrument Type Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Determines the specific instrument type of a single audio sample.

```APIDOC
## detectInstrumentType

### Description
Returns the instrument type of an audio sample at the 'fullPathToSample' absolute file path. Can return one of the following types: `DetectInstrumentType.INVALID`, `DetectInstrumentType.BASS`, `DetectInstrumentType.BOWED_STRING`, `DetectInstrumentType.BRASS`, `DetectInstrumentType.FLUTE`, `DetectInstrumentType.GUITAR`, `DetectInstrumentType.KEYBOARD`, `DetectInstrumentType.MALLET`, `DetectInstrumentType.ORGAN`, `DetectInstrumentType.PLUCKED_STRING`, `DetectInstrumentType.REED`, `DetectInstrumentType.SYNTH`, `DetectInstrumentType.VOCAL`.

### Method Signature
`mir.detectInstrumentType('fullPathToSample')`

### Parameters
- **fullPathToSample** (string) - Required - The absolute file path to the audio sample.
```

--------------------------------

### Scalar Types

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Details the properties and functions for scalar types (Bool, Int, Real, String).

```APIDOC
## Scalars

Basic types which contain a single value: Bool, Int, Real, String.

### Properties

- `scalar.type`: Returns the value type.
- `scalar.initial`: Returns true if the value is in the initial state.
- `scalar.value`: Returns the value.

### Functions

- `scalar:reset()`: Resets the value to its initial state.
- `scalar:assign(other)`: Assigns a copy of the other value object.
```

--------------------------------

### Convert POSIX Time to String

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Converts a POSIX timestamp, typically obtained from filesystem operations like lastWriteTime, into a human-readable ISO string format.

```lua
print(posixTime.toString(filesystem.lastWriteTime(...)))
```

--------------------------------

### Iterate Over Container Elements

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

Iterate through elements of a container, such as instrument.groups, using a for loop with indices from 0 to the number of elements minus 1. Access element properties like 'name'.

```lua
for n=0,#instrument.groups-1 do
    print(instrument.groups[n].name)
end
```

--------------------------------

### Access Zone Key Range

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

Accesses and prints the highest key range value of the first zone within the first group of the instrument.

```lua
print(instrument.groups[0].zones[0].keyRange.high)
```

--------------------------------

### Insert Group into Container at Specific Index

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

Insert a deep copy of an existing group into a container at a specified index using the ':insert()' method. This allows for precise placement of elements within the container.

```lua
instrument.groups:insert(0, instrument.groups[3])
```

--------------------------------

### Add New Group to Container

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

Add a new, empty Group object to the end of a container, such as instrument.groups, using the ':add()' method. This is a structural change to the container.

```lua
instrument.groups:add(Group())
```

--------------------------------

### Drum Type Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Determines the specific drum type of a single audio sample.

```APIDOC
## detectDrumType

### Description
Returns the drum type of an audio sample at the 'fullPathToSample' absolute file path. Can return one of the following types: `DetectDrumType.INVALID`, `DetectDrumType.KICK`, `DetectDrumType.SNARE`, `DetectDrumType.CLOSED_HH`, `DetectDrumType.OPEN_HH`, `DetectDrumType.TOM`, `DetectDrumType.CYMBAL`, `DetectDrumType.CLAP`, `DetectDrumType.SHAKER`, `DetectDrumType.PERC_DRUM`, `DetectDrumType.OTHER`.

### Method Signature
`mir.detectDrumType('fullPathToSample')`

### Parameters
- **fullPathToSample** (string) - Required - The absolute file path to the audio sample.
```

--------------------------------

### Peak Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Detects the peak value of an audio sample in decibels (dB). Supports single file processing and batch processing for a folder.

```APIDOC
## Peak Detection

### Description
Returns a floating point number corresponding to the Peak value in dB of an audio sample. Values are in dB, with a maximum at 0dB. If detection fails, the constant `kDetectPeakInvalid` is returned.

### Functions

`mir.detectPeak('fullPathToSample')`

Returns a floating point number corresponding to the Peak value in dB of an audio sample at the 'fullPathToSample' absolute file path. If detection fails the constant `kDetectPeakInvalid` is returned.

`mir.detectPeakBatch('fullPathToFolder')`

Returns a Lua table with samplePath as the table key and a floating point number corresponding to the peak value in dB as the value for all samples in the 'fullPathToFolder' directory. If detection fails the constant `kDetectPeakInvalid` is returned.
```

--------------------------------

### MIR Functions

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Functions for Music Information Retrieval (MIR), enabling the extraction of musical features like pitch and velocity from audio files.

```APIDOC
## MIR functions
Music Information Retrieval (MIR) is the science of retrieving information from music. Among others, it allows the extraction of meaningful features from audio files, such as the pitch or the velocity of a sample. Creator Tools come with a collection of MIR functions, to assist or automate parts of the instrument creation process.
Single functions retrieve information from single files and take as argument an absolute filename (the full path to the sample file). Batch processing functions retrieve information from folders and take as argument an absolute folder name (the full path to the sample folder).
### Note
Note that all functions live in the global MIR table.
```

--------------------------------

### Loudness Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Measures the loudness of an audio sample in decibels (dB). Supports optional frame and hop size parameters for block processing and batch operations.

```APIDOC
## Loudness Detection

### Description
Returns a floating point number corresponding to the Loudness value in dB of an audio sample. Values are in dB, with a maximum at 0dB. The Loudness is calculated over small blocks of audio. Frame size and hop size are optional arguments and default to 0.4 and 0.1 seconds respectively if not specified. If detection fails, the constant `kDetectLoudnessInvalid` is returned.

### Functions

`mir.detectLoudness('fullPathToSample', frameSizeInSeconds, hopSizeInSeconds)`

Returns a floating point number corresponding to the Loudness value in dB of an audio sample at the 'fullPathToSample' absolute file path. Frame size and hop size are optional arguments and default to 0.4 and 0.1 respectively if not specified. If detection fails the constant `kDetectLoudnessInvalid` is returned.

`mir.detectLoudnessBatch(‘fullPathToFolder’, frameSizeInSeconds, hopSizeInSeconds)`

Returns a Lua table with samplePath as the table key and a floating point number corresponding to the Loudness value in dB as the value for all samples in the 'fullPathToFolder' directory. Frame size and hop size are optional arguments and default to 0.4 and 0.1 respectively if not specified. If detection fails the constant `kDetectLoudnessInvalid` is returned.
```

--------------------------------

### Rename Groups in a Loop

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

Assign new names to groups within a loop, prefixing with 'grp_' and the index. This demonstrates modifying multiple elements.

```lua
for n=0,#instrument.groups-1 do
    instrument.groups[n].name = 'grp_'..n
end
```

--------------------------------

### RMS Detection

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/binding-reference

Calculates the Root Mean Square (RMS) value of an audio sample in decibels (dB). Allows optional frame and hop size parameters for block processing.

```APIDOC
## RMS Detection

### Description
Returns a floating point number corresponding to the RMS value in dB of an audio sample. Values are in dB, with a maximum at 0dB. The RMS is calculated over small blocks of audio. Frame size and hop size are optional arguments and default to 0.4 and 0.1 seconds respectively if not specified. If detection fails, the constant `kDetectRMSInvalid` is returned.

### Functions

`mir.detectRMS('fullPathToSample', frameSizeInSeconds, hopSizeInSeconds)`

Returns a floating point number corresponding to the RMS value in dB of an audio sample at the 'fullPathToSample' absolute file path. Frame size and hop size are optional arguments and default to 0.4 and 0.1 respectively if not specified. If detection fails the constant `kDetectRMSInvalid` is returned.

`mir.detectRMSBatch(‘fullPathToFolder’, frameSizeInSeconds, hopSizeInSeconds)`

Returns a Lua table with samplePath as the table key and a floating point number corresponding to the RMS value in dB as the value for all samples in the 'fullPathToFolder' directory. Frame size and hop size are optional arguments and default to 0.4 and 0.1 respectively if not specified. If detection fails the constant `kDetectRMSInvalid` is returned.
```

--------------------------------

### Change Group Name

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference

Modify the 'name' property of a group directly. This can be done for individual groups or within a loop.

```lua
instrument.groups[0].name = "Release"
```

--------------------------------

### Change Container Element Property

Source: https://www.native-instruments.com/ni-tech-manuals/creator-tools-manual/en/scripting-reference?srsltid=AfmBOorAAL6fV0ehWYPBJnr19T2Mj1TekXWY9mYhSa9RBi2ooThxAuGT

Modify properties of container elements, like the 'name' of a group, by directly assigning a new value. This can be done for individual elements or within a loop.

```lua
instrument.groups[0].name = "Release"
```

```lua
for n=0,#instrument.groups-1 do
    instrument.groups[n].name = 'grp_'..n
end
```
Tokens:
Raw