Notice that help for the functions in the PikaScript standard library is available through the help() function, but the MicroTonic API is only documented here for now.
PLATFORM.OS = 'windows'|'mac'
PLATFORM.CPU = 'x86'|'ppc'
BUILD.TARGET = 'debug' | 'beta' | 'release'
BUILD.VERSION = string (e.g. '3.0.1')
BUILD.NUMBER = number (e.g. 34)
BUILD.DATE = string (e.g. 'Feb 2 2011')
BULLD.TIME = string (e.g. '12:15:16')
BUILD.COMPILER = string (e.g. 'GCC 4.0.1 (Apple Inc. build 5494)')
BUILD.LIBS = string (e.g. 'OSXSDK 1040')
DIRS.DOCUMENTATION
DIRS.PRESETS
DIRS.DRUM_PATCHES
DIRS.SCRIPTS
Paths to various installation directories. These are always full absolute paths ending with a directory slash ('/' or '\'). DIRS.SCRIPTS is the default directory used when loading and saving files without specifying an absolute path.
::isRepeating = true | false
If ::isRepeating is true the user is running the script by shift-clicking the script menu button. Usually this means you should rerun the algorithms using the same parameters as last time without interrupting to ask the user for input.
By using these constants (instead of literal numbers) you can achieve future compatibility in case some configuration in MicroTonic is changed in a future version.
CHANNEL_COUNT = 8
Drum channel count. Drum channels are indexed from 1 to 8.
PATTERN_COUNT = 12
Pattern count. Patterns are indexed from 'a' to 'l'.
LAST_PATTERN = 'l'
Last pattern index. To iterate all patterns you could write:
for (ptn = 'a'; ptn <= LAST_PATTERN; ptn = char(ordinal($0) + 1)) /* do something */
or
for (i = 0; i < PATTERN_COUNT; ++i) { ptn = char(ordinal('a') + i); /* do something */ }
PROGRAM_COUNT = 16
Number of programs. Programs are indexed from 1, e.g. to iterate all programs you could write:
for (pgm = 1; pgm <= PROGRAM_COUNT; ++pgm) /* do something */
PATTERN_STEP_COUNT = 16
Number of steps in a pattern. Pattern data is represented by strings containing '-' and '#'. The step count is the length of these strings.
GLOBAL_PARAM_COUNT = 15
Number of global parameters.
FREQ_VALUE_C4 = 0.4725600599127338
The frequency value for middle C (523.25 Hz) on "OscFreq", "NFilFrq" and "EQFreq".
OCTAVE_STEP = 0.1003433318879937
The parameter value step for a full octave.
PARAMS.n = 215
PARAMS.0 = 'Morph'
PARAMS.1 = 'Pattern'
.
.
PARAMS.15 = 'OscWave.1'
.
.
PARAMS.20 = 'ModRate.1'
.
.
PARAMS.40 = 'OscWave.2'
.
.
PARAMS.214 = 'ModVel.8'
DRUM_PATCH_PARAMS.n = 25
DRUM_PATCH_PARAMS.0 = 'OscWave'
DRUM_PATCH_PARAMS.1 = 'OscFreq'
.
.
DRUM_PATCH_PARAMS.5 = 'ModRate'
.
.
DRUM_PATCH_PARAMS.24 = 'ModVel'
Drum patch and global parameters are usually accessed via their symbolic names (although some functions also take an index). The PARAMS and DRUM_PATCH_PARAMS arrays can be used to look up symbolic names for specific parameters indexes. Notice that the PARAMS array contains parameters for all eight drum patches as well as global parameters.
PARAM_STEPS.OscWave.1 = 3
etc
DRUM_PATCH_PARAM_STEPS.OscWave = 3
etc
The PARAM_STEPS and DRUM_PATCH_PARAM_STEPS arrays will give you the number of discrete steps for discrete parameters
("undefined" for continuous parameters, so you can check which parameters are discrete by using exists() ).
abort()
Terminates the script by throwing an "exception" that will not display any error message. (You can catch this exception with try(). The exception string will be empty.)
See also: throw(), try()
+string = ask('question', ['defaultAnswer'])
Lets the user respond with a string to 'question' through a simple text edit dialog. If the user clicks the cancel button, the script will be aborted with an "exception". (You can catch this exception with try(). The exception string will be empty.)
See also: display(), try()
'fullpath' = browse(['type'])
Opens a file browser window and returns the path browsed to. 'type' can be 'open' (default) or 'save' (opens a "save as" file dialog). If the user presses cancel, the script will be aborted with an "exception". (You can catch this exception with try(). The exception string will be empty.)
See also: dir(), fullPath(), load(), save(), try()
@target = createElement('type', @target)
Creates a new initialized preset, drum-patch, pattern or midi-config structure ('type' should be 'preset', 'drumPatch', 'pattern' or 'midiConfig'). Returns the input @target. See Structures for more info on the various element data.
See also: getElement(), setElement()
dir('path', >callback)
List files in 'path' and calls >callback for every file. Forward slash ('/') in paths work on both Windows and OS X, backward slash ('\') only works on Windows. 'path' is expected to be an UTF-8 encoded path. If the path is not an "absolute full path" it is considered relative to the script directory. >callback will receive the following arguments:
See also: browse(), fullPath(), load(), save(), wildmatch()
'button' = display('message', ['type' = 'plain'], ['buttons' = 'ok'], ['defaultButton' = 'ok'])
Displays a message box (a so called "alert") and returns the name of the button pressed. 'type' can be any of 'plain', 'question', 'warning', 'info' and 'error'. 'buttons' can be 'ok', 'ok cancel', 'retry cancel', 'yes no', 'yes no cancel' or 'abort retry ignore'. Naturally, 'defaultButton' can be any of the buttons just listed.
'fullpath' = fullPath('base', 'path')
Canonicalizes the relative 'path' against the 'base' path (i.e. returns a distinct full path specification). E.g., fullPath("./", 'file') returns the absolute path to 'file' in the current working dir. fullPath('file', "../") returns the absolute path to the parent directory for 'file'. Pass void for 'base' to make a path relative to the script folder.
See also: browse(), dir(), load(), save()
@target = getElement('type', @target)
Gets current preset, drum-patch (of current channel), pattern (currently selected) or midi-config into @target ('type' should be 'preset', 'drumPatch', 'pattern' or 'midiConfig'). Returns the input @target. See Structures for more info on the various element data.
See also: createElement(), setElement()
+float = getParam('param'|+index)
Retrieves the current setting of a single parameter. 'param' is a string or number (e.g. 'ModRate.1' and 20 is equivalent). The returned value is a floating point number between 0 and 1.
See also: getElement(), paramText(), setParam()
?bool = isMarshaledFormat('type', 'string')
Returns true if 'string' is valid MicroTonic file / clipboard format ('type' should be 'preset', 'drumPatch', 'pattern' or 'midiConfig').
See also: marshal(), unmarshal()
'string' = load('path')
Loads a file. 'path' is expected to be an UTF-8 encoded path. If the path is not an "absolute full path" it is considered relative to the script directory. Alternatively, if the file does not exist and a built-in resource exists with the name, the resource is loaded instead (e.g. 'debug.pika'). Forward slash ('/') in paths work on both Windows and OS X, backward slash ('\') only works on Windows.
See also: browse(), dir(), fullPath(), save()
'string' = marshal('type', @source)
Converts a structure (in @source) to MicroTonic file / clipboard format ('type' should be 'preset', 'drumPatch', 'pattern' or 'midiConfig'). See Structures for more info on the various element data.
See also: createElement(), getElement(), isMarshaledFormat(), unmarshal()
'text' = paramText('param'|+index, +value, [?highPrecision = false], [@context])
Converts a parameter value to a human readable string. +value must be a floating point number between 0 and 1. If ?highPrecision is true, the returned text will have enough precision to preserve all the bits of the original floating-point value. @context is optional and if present should reference a "drumPatch" structure. Some parameter's textual representation depend on other parameter settings (such as "ModRate" depending on "ModMode"), and @context can be used to declare these settings. If @context is omitted, the currently active drum patch is used.
See also: getParam(), paramValue()
+value = paramValue('param'|+index, 'text', [@context])
Converts a human readable string to a parameter value. paramValue() will return a default standard value (for the parameter) if it is not convertable. @context is optional and if present should reference a "drumPatch" structure. Some parameter's textual representation depend on other parameter settings (such as "ModRate" depending on "ModMode"), and @context can be used to declare these settings. If @context is omitted, the currently active drum patch is used.
See also: paramText(), setParam()
parseArray('string', @array)
Parses 'string' that represents an array in "NumbStruck" format (the encoding scheme used for all file formats in Sonic Charge products). The result will be stored under @array. Notice that "NumbStruck" parsing is very forgiving. Any string is considered valid "NumbStruck" format, although only correctly formatted strings will actually generate any data.
See also: parseStruct()
parseStruct('string', @struct)
Parses 'string' that represents a struct / associative array in "NumbStruck" format (the encoding scheme used for all file formats in Sonic Charge products). The result will be stored under @struct. Notice that "NumbStruck" parsing is very forgiving. Any string is considered valid "NumbStruck" format, although only correctly formatted strings will actually generate any data.
See also: parseArray()
print('string')
Traces (use "DebugView" to view on Windows and "Console" on Mac). (Replacing the standard PikaScript print() function.)
See also: display()
+float = random(+max)
Returns a pseudo-random number between 0 and +max. (Replacing the standard PikaScript random() function with a better implementation.)
See also: randomInt()
+integer = randomInt()
Returns a random 32-bit value ("unsigned").
See also: random
'string' = readClipboard()
Reads a string from the clipboard. On Windows, CR LF ("\r\n") are automatically translated to LF ("\n").
See also: writeClipboard()
save('path', 'contents')
Saves a file. 'path' is expected to be an UTF-8 encoded path. If the path is not an "absolute full path" it is considered relative to the script directory. Forward slash ('/') in paths work on both Windows and OS X, backward slash ('\') only works on Windows.
See also: browse(), dir(), fullPath(), load()
select('type', +index|'pattern')
Selects the current program, drum channel or pattern ('type' should be 'program', 'channel' or 'pattern'). The range for programs are 1 to 16 (defined by PROGRAM_COUNT). The range for channels are 1 to 8 (defined by CHANNEL_COUNT). The range for patterns are 'a' to 'l' (defined by LAST_PATTERN).
See also: selected()
+index|'pattern' = selected('type')
Returns the currently selected program, drum channel or pattern ('type' should be 'program', 'channel' or 'pattern'). The range for programs are 1 to 16 (defined by PROGRAM_COUNT). The range for channels are 1 to 8 (defined by CHANNEL_COUNT). The range for patterns are 'a' to 'l' (defined by LAST_PATTERN).
See also: select()
@source = setElement('type', @source)
Updates current preset, drum-patch (for current channel), pattern (currently selected) or midi-config from source ('type' should be 'preset', 'drumPatch', 'pattern' or 'midiConfig'). Returns the input @source.
See also: createElement(), getElement()
setParam('param'|+index, +value)
Updates a single parameter immediately. 'param' is a string or number (e.g. 'ModRate.1' and 20 is equivalent). +value must be a floating point number between 0 and 1.
See also: setElement(), getParam(), paramValue()
@target = unmarshal('type', 'string', @target)
Converts MicroTonic file / clipboard format to a structure in @target ('type' should be 'preset', 'drumPatch', 'pattern' or 'midiConfig'). Returns the input @target.
See also: isMarshaledFormat(), marshal(), setElement()
writeClipboard('string')
Puts a string to the clipboard. On Windows, LF ("\n") are automatically translated to CR LF ("\r\n").
See also: readClipboard()
createElement(), getElement(), setElement(), marshal() and unmarshal() work on entire presets, drum patches, patterns and midi configurations. In PikaScript these are represented by "monolithic" PikaScript structures.
.Choke = 0 | 1
.DistAmt = 0 .. 1
.EQFreq = 0 .. 1
.EQGain = 0 .. 1
.Level = 0 .. 1
.Mix = 0 .. 1
.ModAmt = 0 .. 1
.ModMode = 0 (decay) | 0.5 (sine) | 1 (noise)
.ModRate = 0 .. 1
.ModVel = 0 .. 1
.NEnvAtk = 0 .. 1
.NEnvDcy = 0 .. 1
.NEnvMod = 0 (exponential) | 0.5 (linear) | 1 (modulated)
.NFilFrq = 0 .. 1
.NFilMod = 0 (lp) | 0.5 (bp) | 1 (hp)
.NFilQ = 0 .. 1
.NStereo = 0 | 1
.NVel = 0 .. 1
.OscAtk = 0 .. 1
.OscDcy = 0 .. 1
.OscFreq = 0 .. 1
.OscVel = 0 .. 1
.OscWave = 0 (sine) | 0.5 (triangle) | 1 (sawtooth)
.Output = 0 | 1
.Pan = 0 .. 1
.modified = false | true
.name = string
.path = string | void
Parameter names are capitalized and their values are normalized from 0 to 1 (inclusively). You can use paramText() and paramValue() to convert values to and from their natural human readable units.
.channelCC.1.Choke = void | 0 .. 127
.channelCC.1.DistAmt = void | 0 .. 127
.channelCC.1.EQFreq = void | 0 .. 127
.
.
.channelCC.8.Pan = void | 0 .. 127
.globalCC.FillRate = void | 0 .. 127
.globalCC.MastVol = void | 0 .. 127
.globalCC.Morph = void | 0 .. 127
.globalCC.Pattern = void | 0 .. 127
.globalCC.PlayStop = void | 0 .. 127
.globalCC.StepRate = void | 0 .. 127
.globalCC.Swing = void | 0 .. 127
.improvedCCScaling = false | true
.midiCCAutomates = false | true
.midiCCOnSelectedChannel = false | true
.midiNotesSelectChannel = false | true
.midiReceiveChannel = void | 1 .. 16
.midiTransmitChannel = void | 1 .. 16
.notes.Mute.1 = void | 0 .. 127
.notes.Mute.2 = void | 0 .. 127
.
.
.notes.Mute.8 = void | 0 .. 127
.notes.Pattern.a = void | 0 .. 127
.notes.Pattern.b = void | 0 .. 127
.
.
.notes.Pattern.l = void | 0 .. 127
.notes.Program.1 = void | 0 .. 127
.notes.Program.2 = void | 0 .. 127
.
.
.notes.Program.16 = void | 0 .. 127
.notes.Start = void | 0 .. 127
.notes.Stop = void | 0 .. 127
.notes.Trigger.1 = void | 0 .. 127
.notes.Trigger.2 = void | 0 .. 127
.
.
.notes.Trigger.8 = void | 0 .. 127
.patternNoteMode = 'SwitchNext' | 'SwitchNow' | 'Retrigger' | 'RetriggerGated'
.patternsSendMidi = false | true
.pitchWheelRange = 1 | 2 | 3 | 4 | 7 | 12 | 19 | 24
.pitchedMode = false | true
.supportMidiNoteOff = false | true
.supportMidiProgramChange = false | true
.1.accents = string (e.g. '----####----####')
.1.fills = - " -
.1.triggers = - " -
.2.accents
.2.fills
.2.triggers
.
.
.8.accents
.8.fills
.8.triggers
.length = 1 .. 16
accents, fills and triggers are arrays of 16 on / off switches in the form of strings where '-' equals off and '#' equals on.
.FillRate = 0 .. 1
.MastVol = 0 .. 1
.Mute.1 = 0 | 1
.Mute.2 = 0 | 1
.
.
.Mute.8
.Pattern = 0 .. 1 (in 1 / 12 steps)
.PlayStop = 0 (forced stop) | 0.33333 (stop) | 0.66666 (play) | 1 (forced play)
.StepRate = 0 (1/8) | 0.25 (1/8T) | 0.5 (1/16) | 0.75 (1/16T) | 1 (1/32)
.Swing = 0 .. 1
.drumPatches.1.Choke = see drumPatch Structure
.drumPatches.1.DistAmt
.drumPatches.1.EQFreq
.
.
.drumPatches.8.path
.modified = false | true
.name = string
.path = string | void
.patterns.a.1.accents = see pattern Structure
.patterns.a.1.fills
.patterns.a.1.triggers
.
.
.patterns.l.length = 1 .. 16
.tempo = number
The following files are compiled into the binary. You can run or load them using their filenames only: