Functions

Cantabile's expression engine supports the following functions. See also the Variable Reference and Sys-ex Expressions.

Math Functions

.NET Math functions: All the static functions of the .NET Math class
clamp(value,min,max): Clamps a value between a specified range
hi7(x): returns the high-7 bits of a 14-bit number
hibyte(x): returns the high-8 bits of a 16-bit number
lo7(x): returns the low-7 bits of a 14-bit number
lobyte(x): returns the low-8 bits of a 16-bit number
int(x), uint(x), long(x), ulong(x), short(x), ushort(x), byte(x), sbyte(x): converts a value to a specified integer type (typically used for forcing a floating point value to integer)

Miscellaneous Functions

length(x): returns the number of elements in an array, the number of characters in a string or 1 for other types.

String Functions

ASCII(str)

ASCII-7 encodes a string, returning a byte array

formatNumber(value, formatString)

Formats a number using a C# double format specifier. eg: formatNumber(123.123456, "N2") to format to 2 decimal places.

EndsWith(a, b)

Checks if string a ends with b. (Case insensitive)

StartsWith(a, b)

Checks if string a starts with b. (Case insensitive)

strcat(a,b)

joins two strings together, although the + operator can also be used to join strings.

strhas(str, find)

returns true if the string find is contained in str, otherwise false. The comparison is case-insensitive and culture invariant.

strmatch(str, regex)

returns true if the string str matches the regular expression regex. The comparison is case-insensitive and culture invariant.

strpart(str, i)

splits a string on semicolon ; characters and returns the ith part, or an empty string if not enough parts are available.

eg: strpart("Apples;Pears;Bananas", 1) returns "Pears".

strstr(str, find)

returns the zero-based index of the first occurrence of find in str, or -1 if not found. The comparison is case-insensitive and culture invariant.

substr(str,pos)

returns a sub-string of str starting at character pos. If pos is negative, returns the end of the string

substr(str,pos,length)

returns a length characters from str starting at character pos. If pos is negative, returns the end of the string

UTF7(str)

UTF-7 encodes a string, returning a byte array

UTF8(str)

UTF-8 encodes a string, returning a byte array

UTF16(str)

UTF-16 (little endian) encodes a string, returning a byte array

UTF16_be(str)

UTF-16 (big endian) encodes a string, returning a byte array

Velocity and Control Curve Functions

CCToGain(value)

Maps a coarse controller value (0-127) to a gain scalar using the user-selected MIDI gain control curve.

curve(curveKind, curveAmount, value)

Converts a value using one of Cantabile's built-in a velocity curves.

curveKind: one of "enhance", "expand", "enhance-1", "expand-1"
curveAmount: the curve amount from -1.0 to 1.0 (and where 0.0 = linear mapping)
value: a position on the curve from 0.0 to 1.0
returns: the curve value at the position from 0.0 to 1.0

fineCCToGain(value)

Maps a fine controller value (0-16383) to a gain scalar using the user-selected MIDI gain control curve.

gainToFineCC(value)

Maps a gain scalar to a fine controller value (0-16383) using the user-selected MIDI gain control curve.

gainToCC(value)

Maps a gain scalar to a coarse controller value (0-127) using the user-selected MIDI gain control curve.

positionToScalar(controlCurveName, value)

Converts a control curve position to a scalar gain value using one of the user-selected control curves.

controlCurveName: "gain", "midi" or "levels"
value: a control curve position from 0.0 to 1.0
returns: a scalar gain value (ie: where 1.0 = 0dB)

scalarToPosition(controlCurveName, value)

Converts a a scalar gain value to a control curve position using one of the user-selected control curves.

controlCurveName: "gain", "midi" or "levels"
value: a scalar value to be converted
returns: a control curve position from 0.0 to 1.0

Decibel Functions

formatDb(value [, muteString]): Formats a decibel value to a string. If less than approx -60b returns -∞ or the muteString if supplied.
formatGain(value [, muteString]): Formats a scalar gain value to decibels string. If less than approx -60b returns -∞ or the muteString if supplied.
fromDb(value [, limit]): Converts a decibel value to scalar. If limit specified and value < limit returns zero.
toDb(value [, limit]): Converts a scalar gain value to decibels. If limit specified and value < limit returns negative infinity.

MIDI Functions

formatMidiNote(value): Formats a MIDI note number using Cantabile current settings for display note names.
formatProgramNumber(value): Formats a program number according to current Cantabile settings for displaying program numbers.
midivarlen(x): encodes a multi-byte integer using 7-bit MIDI variable length encoding.
parseProgramNumber(string): parses a Cantabile formatted banked program number returning a zero based banked program number.
parseMidiNote(string): parses a Cantabile formatted MIDI note name (eg: "C#4") and returns MIDI note number.

Onscreen Keyboard State

These functions return the state of the onscreen keyboard. In all cases the MIDI channel number is optional and defaults to 1 if not specified.

is_note_held(noteNumber, [channel]): Returns 1 if the note is held, otherwise 0
lowest_held_note([channel]): Returns the MIDI note number of the lowest held note, or -1 if no held notes
lowest_held_pitch_class([channel]): Returns the pitch class as a string (eg; "C", "C#" etc...) of the lowest held note
all_notes_held(notesArray, [channel]): Returns 1 if all notes in the array are held, othersize 0 eg: all_notes_held([60,64,67], 2) checks if all notes in middle CMaj on MIDI channel 2 is held
any_notes_held(notesArray, [channel]): Returns 1 if any notes in the array are held, otherwise 0 eg: any_notes_held([60,64,67], 2) checks if any notes in middle CMaj on MIDI channel 2 are held
is_pitch_class_held(pitch_class, [channel]): Returns 1 if at all specified pitch classes are held. eg: is_pitch_class_held("CEG") returns 1 if at any C, E and G notes are held (ie: all three must be held, but in any octave)
any_pitch_class_held(pitch_class, [channel]): Returns 1 if at any of the specified pitch classes are held. eg: any_pitch_class_held("CEG") returns 1 if any C, E or G notes are held
cc(controllerNumber, [channel]): The current value of a continuous controller
finecc(controllerNumber, [channel]): The current value of a fine continuous controller
program([channel]): The currently selected program number
bankedProgram([channel]): The currently selected banked program number
pitchBend([channel]): The current pitch bend value
channelPressure([channel]): The current channel pressure value
rpnCoarse(paramNumber, [channel]): The current coarse value of an RPN parameter
rpnFine(paramNumber, [channel]): The current fine value of an RPN parameter
nrpnCoarse(paramNumber, [channel]): The current coarse value of a NRPN Parameter
nrpnFine(paramNumber, [channel]): The current fine value of a NRPN Parameter

Roland Sys-ex Functions

RolandCheckSum(array): calculates the Roland sys-ex checksum of an array. (The array is flattened to a byte array using the same rules as for sys-ex expressions)
RolandPack16(value): packs a 16-bit value into 4 bytes with 4-bits in each byte (MSB first), as used in Roland sys-ex. (aaaabbbbccccdddd => 0000aaaa 0000bbbb 0000cccc 0000dddd)
RolandPack8(value): packs an 8-bit value into 2 bytes with 4-bits in each byte (MSB first), as used in Roland sys-ex. (aaaabbbb => 0000aaaa 0000bbbb)

MIDI Generations Functions

These functions are only available in the "Sys-Ex / Raw Bytes" binding point target and can be used to generate raw MIDI data.

Note the parameters to these functions are all zero-based, except the MIDI channel number which is 1 based.

midi.noteOn(channel, noteNumber, velocity): generates the 3-bytes of a note on event.
midi.noteOff(channel, noteNumber): generates a 3-byte note on event with velocity zero (ie: a note off event)
midi.cc(channel, controllerNumber, controllerValue): generates a standard 3-byte continuous controller event.
midi.fine_cc(channel, controllerNumber, controllerValue): generates a fine-valued (0-16384) continuous controller event
midi.after_touch(channel, noteNumber, value): generates a 3-byte after-touch event
midi.program_change(channel, programNumber): generates a 2-byte program change event
midi.bank_select(channel, msb, lsb): generates a bank select messages as 2x CC events
midi.banked_program_change(channel, programNumber): generates a banked program change as 2x CC events and 1x program change event
midi.rpn(channel, parameterNumber, parametervalue): generates a fine-RPN event as series of 4x continuous controller events
midi.nrpn(channel, parameterNumber, parametervalue): generates a fine-NRPN event as series of 4x continuous controller events
midi.channel_pressure(channel, pressure): generates a 2-byte channel pressure event
midi.pitch_bend(channel, value): generates a 3-byte pitch bend event
midi.delay(milliseconds): generates a special sys-ex event encoding a delay period. This special sys-ex is intercepted by Cantabile when processing the generated MIDI byte stream and causes a sample accurate delay before the following events are emitted.