Binding Reference

Type

Base type of all object types. The following accessors are defined for objects off all derived types:

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`

Scalars

Basic types which contain a single value:

Bool	Boolean, true or false
Int	64 bit signed integer (can be negative)
Real	64 bit floating point number
String	Text

For a scalar object of these types the following accessors are defined:

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

Vector

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

For a vector object the following accessors are defined:

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

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-safe record with named fields.

For a struct object the following accessors are defined:

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 fields40
`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

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

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)

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.

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.

Pitch detection

The pitch detection tries to detect the fundamental frequency of a monophonic/single note sample. It 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

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

Peak, RMS & Loudness detection

Loudness, Peak, and RMS 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.

In the case that Loudness, Peak, or RMS detection fails, they will return constants kDetectLoudnessInvalid, kDetectPeakInvalid, kDetectRMSInvalid, which all resolve to 1000000.0f. When logging Peak, RMS, or Loudness values, invalid detections will be logged in numerical form.

Note

It is advised to compare against respective <k-type-invald> constants in your scripts, since there is no guarantee that the numerical value will not change.

Functions
Peak detection
`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
RMS detection
`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.
Loudness detection
`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.

Examples

peakVal = mir.detectPeak('fullPathToSample')

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

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

Analyses all audio samples in the 'fullPathToFolder' directory and stores the resulting RMS values in the Lua table rmsBatchData. For the calculation, Frame and Hop size have been specified to 0.02 and 0.01 respectively.

Type detection

Type detection is a means to determine which category a given audio sample belongs to. Currently, Creator Tools supports detection of three distinct types: Sample Type, Drum Type, and Instrument Type. Sample Type is used to determine if a sample is either a drum, or an instrument. Drum Type and Instrument Type both determine which drum or instrument category a sample belongs to. For each type, an INVALID category is defined as helper for default initialisation.

Furthermore, in the case that Sample Type, Drum Type, or Instrument Type detection fails, they will return their respective INVALID type, which all resolve to -1. When logging Sample Type, Drum Type, or Instrument Type values, invalid detections will be logged in numerical form. However, it is advised to compare against respective <type.INVALID> constants in your scripts - since there is no guarantee that the numerical value will not change.

Note

Note that these type detection functions are designed to process one-shot audio samples.

Functions
Sample type detection
`mir.detectSampleType('fullPathToSample')`	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`
`mir.detectSampleTypeBatch(‘fullPathToFolder’)`	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.
Drum type detection
`mir.detectDrumType('fullPathToSample')`	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`
`mir.detectDrumTypeBatch(‘fullPathToFolder’)`	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.
Instrument type detection
`mir.detectInstrumentType('fullPathToSample')`	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`
`mir.detectInstrumentTypeBatch(‘fullPathToFolder’)`	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.

Examples

sampleType = mir.detectSampleType('fullPathToSample')

Analyses an audio sample at the 'fullPathToSample' absolute file path and stores the resulting sample type category in sampleType.

drumType = mir.detectDrumType('fullPathToSample')

Analyses an audio sample at the 'fullPathToSample' absolute file path and stores the resulting drum type category in drumType.

instType = mir.detectInstrumentType('fullPathToSample')

Analyses an audio sample at the 'fullPathToSample' absolute file path and stores the resulting instrument type category in instType.

sampleTypeBatchData = mir.detectSampleTypeBatch(‘fullPathToFolder’)

Analyses audio samples in the 'fullPathToFolder' directory and stores the resulting sample types in the Lua table sampleTypeBatchData.

Loop detection

The new findLoop() MIR function, analyzes and suggests loop points for samples. The function returns two variables for the loop start and the loop end, which can then be used to set the loop points for the respective zone.

The full syntax for the function is findLoop(filePath, minStart, maxEnd, minLength). Apart from the path, all other arguments are optional. If only the path is supplied then the rest of the arguments are calculated by the algorithm.

Tip

You can use the existing MIR functions of Creator Tools, to determine different findLoop() behaviours depending on the various sample features.

Example

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

Binding Reference

Type

Scalars

Vector

Struct

Algorithms

File system

Examples

Functions

PosixTime

Note

Example

MIR functions

Note

Pitch detection

Examples

Peak, RMS & Loudness detection

Note

Examples

Type detection

Note

Examples

Loop detection

Tip

Example

Search results