Native Instruments Kontakt 1.1 Creator Tools

1
A suite of tools developed to support
the instrument creation process

Contents

Application Manual
CREATOR TOOLS ����������������������������������������������������������������������������������������������������������������������������������4
DEBUGGER ��������������������������������������������������������������������������������������������������������������������������������������������4
INSTRUMENT EDITOR �������������������������������������������������������������������������������������������������������������������������� 6
GUI DESIGNER ���������������������������������������������������������������������������������������������������������������������������������������8
Scripting Reference
SCRIPTING BASICS ���������������������������������������������������������������������������������������������������������������������������� 15
SCRIPT PATH�����������������������������������������������������������������������������������������������������������������������������������15 READ PROPERTIES AND PRINT THEM ����������������������������������������������������������������������������������������� 15 ITERATE OVER CONTAINERS ���������������������������������������������������������������������������������������������������������15 WORKING WITH CONTAINERS ������������������������������������������������������������������������������������������������������16
BINDING REFERENCE
TYPE ������������������������������������������������������������������������������������������������������������������������������������������������ 17
OPERATORS ��������������������������������������������������������������������������������������������������������������������������������17 FUNCTIONS ��������������������������������������������������������������������������������������������������������������������������������� 17 PROPERTIES ��������������������������������������������������������������������������������������������������������������������������������18
SCALARS ����������������������������������������������������������������������������������������������������������������������������������������� 18
PROPERTIES ��������������������������������������������������������������������������������������������������������������������������������18 FUNCTIONS ��������������������������������������������������������������������������������������������������������������������������������� 19
VECTOR ������������������������������������������������������������������������������������������������������������������������������������������� 19
CONSTRUCTORS�������������������������������������������������������������������������������������������������������������������������19 OPERATORS ��������������������������������������������������������������������������������������������������������������������������������20 PROPERTIES �������������������������������������������������������������������������������������������������������������������������������� 20 FUNCTIONS ��������������������������������������������������������������������������������������������������������������������������������� 21
STRUCT �������������������������������������������������������������������������������������������������������������������������������������������22
CONSTRUCTORS�������������������������������������������������������������������������������������������������������������������������22 OPERATORS ��������������������������������������������������������������������������������������������������������������������������������22 PROPERTIES ��������������������������������������������������������������������������������������������������������������������������������22 FUNCTIONS ���������������������������������������������������������������������������������������������������������������������������������23
2
Contents
ALGORITHMS ����������������������������������������������������������������������������������������������������������������������������������24
FREE FUNCTIONS �����������������������������������������������������������������������������������������������������������������������24
FILE SYSTEM �����������������������������������������������������������������������������������������������������������������������������������25
EXAMPLES ����������������������������������������������������������������������������������������������������������������������������������25 FUNCTIONS ��������������������������������������������������������������������������������������������������������������������������������� 25 OPERATIONAL �����������������������������������������������������������������������������������������������������������������������������26
POSIXTIME �������������������������������������������������������������������������������������������������������������������������������������� 28
EXAMPLES ����������������������������������������������������������������������������������������������������������������������������������28 FUNCTIONS ��������������������������������������������������������������������������������������������������������������������������������� 28 CONVERSIONS ���������������������������������������������������������������������������������������������������������������������������� 28
MIR FUNCTIONS �����������������������������������������������������������������������������������������������������������������������������29
PITCH DETECTION ����������������������������������������������������������������������������������������������������������������������29 PEAK, RMS & LOUDNESS DETECTION �������������������������������������������������������������������������������������� 30
3

Application Manual

Application Manual

Creator Tools

A suite of tools developed to support the instrument creation process� It consists of the Debugger, the Instrument Editor and the GUI Designer� Switching between the tools is possible from the top tabs, or by using the shortcuts F1 (Debugger), F2 (Instrument Editor) and F3 (GUI Designer)� Creator Tools actions can also be triggered via their dedicated shortcuts� Shortcuts act according to which panel the user is focused on�

Debugger

The Debugger connects to all running instances of Kontakt, both plug-in and standalone� It logs messages, warnings and errors coming for KSP, supports inspecting script variables,
provides timestamps per notication and some basic ltering options.
VARIABLE WATCHING (/CT R L- E)
Clicking on the eye icon reveals the Variable Watching area� This is where the current values of all watched variables and arrays are displayed, in order of appearance� For every variable or array that is inspected, an entry is created upon initialization and updated every time a value change occurs� All value changes appear also in the Log above, in chronological order�
Inspecting a variable or array is possible via the dedicated KSP commands watch_var and watch_array_idx
For example watch_var($count) inspects the value changes of the variable count and watch_array_idx(%volume,5) inspects the value changes of index 5 of the array volume
Please also refer to the KSP Reference Manual for more details�
FILTER (/C TR L- F )
When active, it reveals the ltering options and applies them.
• Filter by type (Variable Watching, Message, Warning, Error)
• Filter by text (characters in the Message column)
• Filter by Instrument
• Filter by Script slot
4
Application Manual
PAUSE (/CTRL-P)
Suspends the debugging session� While active, the Pause button blinks� Once the session is resumed, all messages that were received during pause will appear�
CLEAR (/CTRL-BACKSPACE)
Clears all content of the Debugger log�
SETTINGS
Denes the behaviour of the Log.
LOG
This is where all notications from Kontakt appear. The Log contains 7 columns:
• Type
• System Time
• Engine Time
• Message
• Instrument
• Script
• Line Type and Message are set, but all other columns can be hidden� Right-clicking on the column header reveals the column menu�
5
Application Manual

Instrument Editor

The Instrument Editor connects to a running instance of Kontakt, either plug-in or standalone, and offers programmatic access to parts of a Kontakt instrument’s structure through Lua-based scripting�
It loads and runs Lua scripts that have been created in a text editor and saved to disk� In
this way an instrument structure can be modied. One can now easily rearrange, add or
remove groups and zones, edit their names and some of their properties, like tune, volume,
and mapping. Limited le system access also allows the creation of new instruments based
on samples on the disk� The added MIR functions (like pitch and RMS detection) assist or automate parts of the instrument creation process�
Some Lua example and tutorial scripts are provided for the above in the application folder, to help you get started if needed� Ideally, the content of the scripts’ folder can be copied to “*user*/Documents/Native Instruments/Creator Tools”�
MULTI RACK MENU
Sets the focus of the tool on the multi rack of one of the connected Kontakt instances�
INSTRUMENT MENU
Sets the focus of the tool to a specic instrument that is loaded in one of the connected Kontakt
instances� Note that instruments with locked edit views, cannot be selected�
PUSH (/CT R L-Shift-↑)
Applies all changes from the Tools‘ side to Kontakt� If changes are not pushed, an indication on the button appears to notify for the pending changes�
PULL (/C TR L- Shift-↓)
Overwrites the current Kontakt state to the tools� Whenever a change takes place on the Kontakt side, Pull needs to be manually pressed in order to apply the changes in the Tools� If changes are not pulled, an indication on the button appears to notify for the pending changes�
CONNECTION INDICATOR
The connection indicator on the top right corner, indicates whether a successful connection between the tools and the Kontakt instances is established�
6
Application Manual
INSTRUMENT TREE VIEW
The instrument structure is displayed in the form of a nested tree� The tree view shows the basic
instrument structure and instrument properties that can be modied.
SCRIPT PANEL
Changes within the Tools happen exclusively via running a Lua script� A script can see and
modify the instrument copy in the Tools. Scripts can be created and modied with an external
editor� The script output will appear in the console output� All console output can be copied to system clipboard via the command /Ctrl-Alt-C�
LOAD (/C TR L- L)
Opens the le explorer in order to locate a .lua le in disk and load it. The lename of the loaded le will then appear in the lename area.
[Currently the Creator Tools Lua runtime on Windows does not support lepaths that contain Unicode characters. Please rename the script’s lepath accordingly to successfully load it.]
OPEN IN TEXT EDITOR (/CT RL- O)
Opens the loaded script le in the system’s default editor.
RUN (/CT RL- R )
Executes the loaded �lua script� Changes are immediately reflected in the Instrument Tree View�
STOP (/C TRL- I)
Stops the execution of the running script� The Instrument Editor state is reverted, as if the script never run�
CLEAR
Clears all content of the Script Output Panel�
7
Application Manual

GUI Designer

The GUI Designer allows one to assemble, customize and reuse Kontakt performance views and
controls without the need to write code. It can generate two types of les, the performance view les (.nckp) and the control les (.nckc).
The performance view les (.nckp) contain all the information about an instrument’s graphical interface. These les are created when a GUI Designer project is saved and can then be loaded
in a KSP script (see also Loading in KSP)�
The control les (.nckc) are les that are created by exporting a single control or a container of controls (see also Panels). These les can then be imported in a later GUI Designer project, shared with collaborators or set the foundation for building custom UI libraries. Control les
cannot be loaded in KSP�
The two main areas of the tool are the Tree View and the Properties�
Tree View
The structure of a Kontakt performance view is displayed here in the form of a tree� A new performance view has one hierarchy level; the root level� More levels can be created when controls are added in panels (see Panels)�
Actions on one or more selected controls can be performed from the Tree View’s context menu�
The context menu actions are:
• Cut (⌘/CT RL-X)
Copies selection to the clipboard and deletes it from the tree
• Copy (/CTR L- C)
Copies selection to the clipboard
• Paste (/C TR L-V)
Pastes the controls from the clipboard above selection
• Duplicate (/C TR L- D)
Duplicates selection
• Rename (↵)
Enters renaming mode for selection
• Delete (/CT RL- )
Deletes selection
8
Application Manual
• Import (/C TR L- I)
Opens the system’s le browser in order to locate and import a control le (.nckc) from the
disk� The imported control will be placed above the currently selected control
• Export (/C TR L- E)
Opens the system’s le browser in order to save the selected control’s le (.nckc) in a
desired location
Adding a control
INSERT CONTROL MENU
A new control can be inserted in the performance view tree from the Insert Control menu� The menu lists all the known Kontakt UI controls, plus a new control called Panel (see Panels)�
IMPORT
Previously exported controls can be added in the tree via the Import function of the context menu� Select a control and right click to reveal the context menu� Click on Import and locate the control’s .nckc le in the system’s le browser. Select Open and the control will be added in the tree, on top of the currently selected control�
PANELS
A panel is a control that can contain one or multiple controls� Unlike the rest of the controls, panels don’t have size� They are very useful for grouping controls that are meant to be handled together� Then one can simultaneously modify the Show, Position or zLayer property of all the controls contained in that panel� The position of a contained control is relative to the panel’s position� This means that the control’s (0,0) position is the current (x,y) position of the panel�
Panels can be nested, so they can contain other panels� If panelA is contained in panelB, then panelA will appear in front of panelB� This is because children panels have a higher zLayer value than their parent panels� One could use this logic to easily create hierarchies in a performance view�
Panels can also be used to keep the tree view organized� They can be expanded or collapsed� When a panel is selected and expanded, new controls will be added on top of the panel’s contained controls� When a panel is selected but collapsed, new controls will be added above it, on the same hierarchy level as the panel�
9
Application Manual
PANELS IN KSP
Panels, like any other control, can also be used with pure KSP outside the GUI Designer, using
the following new command and control parameter:
declare ui_panel $<my_panel_name>
Creates a panel
set_control_par(<control-to-add-ui-ID>,$CONTROL_PAR_PARENT_PANEL,<panel­ui-I D >)
Adds a UI control (or panel) in a panel
Example: Adding the volume knob in the mixer panel.
declare ui_panel $mixer declare ui_knob $volume (0,300,1)
set_control_par(get_ui_id($volume),$CONTROL_PAR_PARENT_PANEL,get_ui_ i d ($ m i xe r))
PROPERTIES
On the right side of the GUI Designer is the Properties area� Here, one can modify the properties of a selected control� Depending on the type of the property, editing can be done via text input, numeric input or dropdown menu selection� When an invalid value is entered, the property will be set to the last valid value� Pressing TAB takes the focus from the Tree View to the Properties area and vice versa�
IMAGE
Image elds take as input the lename of a picture (.png) that is contained in the pictures subfolder of the Resources folder�
Note: The Resources folder is the place to store les that an NKI can use, which are not samples.
For more information please check KSP Reference Manual - Working with the Resource Container.
COLOR
Color elds take as input the hex code (six-digit, three-byte hexadecimal number) of a color. A preview of the set color is displayed on the right side of the color input eld.
10
Application Manual
FONTS
From the dropdown menu, one can select to set 1 of the 25 factory fonts or a custom font� If “Custom” is selected, then the lename of the picture font is expected. Similar to the Image property, the picture font should be contained in the Pictures subfolder of the Resources folder�
UNDO/REDO Undo and Redo actions are available via the usual shortcuts (⌘/CTRL-Z) for Undo and
(Mac: -Shift-Z, Windows: CTRL-Y) for Redo.
FILE MENU
From the File menu on the top right of the tool, one can Save, Save As, Open or create a New
performance view. The GUI Designer saves the last 10 les that have been opened and displays them in the Recent Files list of the File menu. Existing les can also be opened by dragging and dropping the le from the OS to the GUI Designer.
LOADING IN KSP
The Resource Container is a dedicated location to store scripts, graphics, .nka les and
impulse response les that can be referenced by any NKI or group of NKIs that are linked to the
container�
When creating the Resource Container, Kontakt versions that are compatible with the GUI Designer will create a new subfolder named performance_view�
In order for a performance view to be displayed in an NKI, the performance view le (.nckp)
must be stored in the performance_view subfolder of the NKI� It can then be loaded in the NKI
via the KSP command:
load_performance_view(“filename”)
where filename is the lename of the .nckp le without the extension. Performance view lenames can only contain letters, numbers or underscores.
When saving a .nckp le in the GUI Designer, any changes will be automatically applied to the
Kontakt side� This means when editing the performance view of an NKI, if that NKI is loaded in a running Kontakt instance, all changes can be previewed in real time upon Save�
To avoid conflicts, only one performance view le can be loaded per script slot. If needed, more
controls can be additionally declared in the KSP script�
Connecting UI controls to engine parameters still happens via KSP� The variable name of a control contained in a performance view is auto generated based on its hierarchy, with underscore characters as concatenation�
11
Application Manual
Example:
Control knobVolume is contained within panel eqTab, which is also contained within panel mi xerTa b. The KSP variable name of the control will be: mixerTab_eqTab_knobVolume
The KSP variable name of a selected control is displayed at the bottom of the properties area� Click on the Copy button next to it (or use the shortcut /CTRL-Alt-C) to copy the variable name to clipboard�
CREATING AND PREVIEWING YOUR FIRST PERFORMANCE VIEW
• Create a new NKI in Kontakt
• Create the Resource Container for the NKI
Open a new performance view project in GUI Designer and start adding controls
• Make sure all the referenced data (images, picture fonts) are stored in the images subfolder of the NKI’s Resource Container
Save the performance view le in the performance_view subfolder of the NKI’s Resource
Container
In the NKI script editor, write and apply the following script:
on init load_performance_view (“filename”) end on
• You can now continue to edit the performance view in the GUI Designer� Each time you want to
preview any changes in the performance view, save the .nckp le in the GUI Designer.
12

Scripting Reference

Scripting Reference
Lua scripts can be loaded and run in the Instrument Editor tool to assist or automate tasks in the instrument creation process� This section of the documentation contains the scripting basics of the Lua language as well as extension bindings to a Kontakt instrument’s structure�
13
Scripting Reference

Instrument Structure

An instrument is shown as a nested tree with properties and values� Containers like groups and zones are represented as vectors (lists with indices)� Property values are typed and value-
checked so that changes are veried and ignored if the data is invalid. The current structure looks like this:
Instrument Struct name String groups Vector of Group name String volum e Real, -inf..12 tune Real, -36..36 zones Vector of Zone uniqueID Int file String volum e Real, -inf..12 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
Loop modes: 0: Oneshot i.e. off 1: Until end 2: Until end alternating 3: Until release 4: Until release alternating
Future updates will allow more properties to be edited�
14
Scripting Reference

Scripting Basics

Scripting is based on the Lua language� Resources are available online e�g� www�lua�org� The core language has been extended by bindings to the instrument structure� Whenever an instrument is connected and the tree view is displayed, a script can access it via the variable instrum ent

SCRIPT PATH

The global variable scriptPath points to the directory of the executed script�
This is useful for le I/O related workflows.

READ PROPERTIES AND PRINT THEM

A script can print to the console e�g�
print(instru ment)
Prints “Instrument” if an instrument is connected, otherwise “nil” i�e� nothing
print(scriptPath)
Prints the directory of the running script
All properties can be referenced using dots e�g�
print(instru ment.groups[0].name)
Prints the name of the rst group - or an error message if no instrument is connected
print(instru ment.groups[0].zones[0].keyRange.high)
Prints the highest key range value of the rst zone of the rst group

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:
pri nt(# instrument.groups)
Prints the number of groups of the instrument
for n=0,#instrum ent.groups-1 do
print(instrument.groups[n].name)
end
Iterates over the groups of the instrument and prints their names
Note that vectors are zero-indexed! There are ways to iterate containers without using indices�
15
Scripting Reference

WORKING WITH CONTAINERS

Group()
This creates a new object of type Group
print(scriptPath)
Prints the directory of the running script
Structural changes like add, remove, insert are possible:
instrum ent.groups:add(Group())
This adds a new empty group at the end
The next example inserts a deep copy of the 4th group at index 0 i.e. at the beginning:
instrum ent.groups:insert(0, instrument.groups[3])
16
Scripting Reference

Binding Reference

Type

Base type of all object types. The following accessors are dened for objects off all types:
OPERATORS
tostring
Returns a string representation describing the object
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
17
Scripting Reference
PROPERTIES
object.typeinfo
Returns type information as a string in the form Type‘Tag
object.parent
Returns the parent object or nil

Scalars

Basic types which contain a single value:
Bool
Boolean, true or false
Int
64 bit integer (signed i�e� can be negative)
Real
64 bit floating point number
String
Text
PROPERTIES
s c a l a r.t y p e
Returns the value type
scalar.initial
Returns true if the value is in the initial state
scalar.value
Returns the value
18
Scripting Reference
FUNCTIONS
scalar:reset()
Resets the value to its initial state
scalar:assign(other)
Assigns a copy of the other value object

Vector

Type-safe, dynamically sized, zero-indexed, random access container For a vector object the following accessors are dened:
CONSTRUCTORS
vector()
Returns 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
19
Scripting Reference
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 initial
20
FUNCTIONS
vector:set(index, object)
Set 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
Scripting Reference
vector:assign(other)
Inserts object at the end
vector:add(object)
Inserts object at the end
vector:add(value)
Inserts value at the end
ve ctor:insert(index, obje ct)
Inserts object or value before index
ve ctor:insert(index, value)
Inserts value before index
vector:remove(index)
Removes element at index
21
Scripting Reference

Struct

Type-safe, record with named elds.
For a struct object the following accessors are dened:
CONSTRUCTORS
stru ct()
Returns new struct
struct(other)
Returns a copy of the other struct
OPERATORS
#
Returns the number of used elds
pairs
Returns an iterator function for iterating over used elds
value/object = struct.field
Returns the value if eld contains a scalar, otherwise returns the object
struct.field = value
Sets element value of eld
struct.field = object
Assigns object to eld
PROPERTIES
st r u c t.t y pe
Returns the struct type
struct.e m pty
Returns true if the struct has no used elds
struct.initial
Returns true if the struct is initial
22
FUNCTIONS
vector:set(index, object)
Assigns object at index
vector:get(index)
Returns object at index
vector:reset()
Resets the struct to initial
struct:reset(index)
Resets the eld at index
struct:reset(field)
Resets the eld
Scripting Reference
struct:used(field)
Returns true if the eld is used
stru ct:resolve(p ath)
Returns the object at path
struct:assign(other)
Assigns a copy of the other struct
23
Scripting Reference

Algorithms

FREE FUNCTIONS
pa th(o bje ct)
Returns the path to object
res olv e(p ath)
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 eld 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
24
Scripting Reference

File system

The Lua binding is based on the C++ library boost lesystem� The reference documentation describes each function in detail� In contrary to the original C++ design the Lua binding does not
dene an abstraction for path. Instead path always refers to a Lua string.
EXAMPLES
for _,p in filesystem.directory(path) do pri nt(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 table lesystem.
Iterators:
iterator filesystem.directory(path) iterator filesystem.directoryRecursive(path)
Path:
The functions return a string which contains the modied path.
string 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)
25
Scripting Reference
Query:
The functions query a given path�
bool 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)
OPERATIONAL
These functions allow queries on the underlying lesystem.
Path:
bool filesystem.exists(path) bool filesystem.equivalent(path1, path2) int filesystem.fileSize(path) string filesystem.currentPath() string filesystem.initialPath() string filesystem.absolute(path, [base]) string filesystem.canonical(path, [base]) string filesystem.systemComplete(path)
Test :
bool filesystem.isDirectory(path) bool filesystem.isEmpty(path) bool filesystem.isRegularFile(path) bool filesystem.isSymLink(path) bool filesystem.isOther(path)
26
Scripting Reference
Last Write Time:
int filesystem.lastWriteTime(path)
Links:
string filesystem.readSymLink(path) int filesystem.hardLinkCount(path)
Note: For convenience user can declare fs=lesystem and call all lesystem functions using the fs prex:
Example:
fs=filesystem iterator fs.directory(path) iterator fs.directoryRecursive(path)
27
Scripting Reference

PosixTime

Date and time related utility functions�
EXAMPLES
print(posixTimetoString(filesystemlastWriteTime(...)))
Converts lesystem lastWriteTime to a string.
FUNCTIONS
Note that all functions live in the global table posixTime�
CONVERSION
Note that all functions live in the global table posixTime�
string posixTime.toString(int)
Converts the posix-time to an ISO string�
28
Scripting Reference

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 les, 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 les and take as argument an absolute lename (the full path to the sample le). Batch processing functions retrieve information from
folders and take as argument an absolute folder name (the full path to the sample folder)�
Note that all functions live in the global table mir�
PITCH DETECTION
The pitch detection tries to detect the fundamental frequency of a monophonic/single note sample� It ranges from semitone 15 (~20Hz) to semitone 120 (~8�4 kHz)�
Pitch functions return a floating point value corresponding to the MIDI scale (69 = 440Hz)� In case the pitch analysis fails, it will return a value of 0�
pitchVal = mir.detectPitch(‘fullPathToSample’)
Single function call
pitchBatch = mir.detectPitchBatch(‘fullPathToFolder’)
Batch processing
Batch processing will return a Lua table with samplePath as the table key and pitch as the value�
It can be accessed in the following way:
pitchBatchData = mir.detectPitchBatch(‘fullPathToFolder’) pitchValue = pitchBatchData[‘fullPathToSample’]
29
Scripting Reference
PEAK, RMS & LOUDNESS DETECTION
Peak, RMS and Loudness functions return a value in dB, with a maximum at 0dB�
The RMS and Loudness functions are calculated over small blocks of audio� The duration of those blocks is called frame size and is expressed in seconds� The process is repeated in intervals equal to the hop size (also expressed in seconds), until it reaches the end of the sample� The functions return the overall loudest/highest value of the different blocks�
If frame size and hop size are not indicated, the default values 0�4 (frame size in seconds) and 0�1 (hop size in seconds) are applied respectively�
Single Functions
peakVal = mir.detectPeak(‘fullPathToSample’)
Peak detection
rmsVal = mir.detectRMS(‘fullPathToSample’)
rmsVal = mir.detectRMS(‘fullPathToSample’, frameSizeInSeconds, hopSizeInSeconds)
RMS detection
loudnessVal = mir.detectLoudness(‘fullPathToSample’)
loudnessVal = mir.detectLoudness(‘fullPathToSample’, frameSizeInSeconds, hopSizeInSeconds)
Loudness detection
30
Scripting Reference
Batch Processing
Batch processing will return a Lua table with samplePath as the table key and peak (RMS,
Loudness) as the value. It can be accessed in the following way:
peakValue = peakBatchData[‘fullPathToSample’]
peakBatchData = mir.detectPeakBatch(‘fullPathToFolder’)
Peak detection
rmsBatchData = mir.detectRMSBatch(‘fullPathToFolder’)
rmsBatchData = mir.detectRMSBatch(‘fullPathToFolder’, frameSizeInSeconds, hopSizeInSeconds)
RMS detection
loudnessBatchData = mir.detectLoudnessBatch(‘fullPathToFolder’)
loudnessBatchData = mir.detectLoudnessBatch(‘fullPathToFolder’, frameSizeInSeconds, hopSizeInSeconds)
Loudness detection
31
Loading...