Skip to main content

Utilities

The Utilities class contains general-purpose utility methods. All methods are static and should be called using the class name. For example: Utilities.getNoteDetails("C4").

Since: 3.0.0


Propertiesโ€‹

.isBrowserโ€‹

Type: boolean

Indicates whether the execution environment is a browser (true) or not (false)

.isNodeโ€‹

Type: boolean

Indicates whether the execution environment is Node.js (true) or not (false)


Methodsโ€‹

.buildNote(...)โ€‹

Since: version 3.0.0

Converts the input parameter to a valid Note object. The input usually is an unsigned integer (0-127) or a note identifier ("C4", "G#5", etc.). If the input is a Note object, it will be returned as is.

If the input is a note number or identifier, it is possible to specify options by providing the options parameter.

Parameters

Signature: buildNote([input], [options])

ParameterType(s)DefaultDescription
[input]number
string
Note
[options]object
{}
[options.duration]number
InfinityThe number of milliseconds before the note should be explicitly stopped.
[options.attack]number
0.5The note's attack velocity as a float between 0 and 1. If you wish to use an integer between 0 and 127, use the rawAttack option instead. If both attack and rawAttack are specified, the latter has precedence.
[options.release]number
0.5The note's release velocity as a float between 0 and 1. If you wish to use an integer between 0 and 127, use the rawRelease option instead. If both release and rawRelease are specified, the latter has precedence.
[options.rawAttack]number
64The note's attack velocity as an integer between 0 and 127. If you wish to use a float between 0 and 1, use the release option instead. If both attack and rawAttack are specified, the latter has precedence.
[options.rawRelease]number
64The note's release velocity as an integer between 0 and 127. If you wish to use a float between 0 and 1, use the release option instead. If both release and rawRelease are specified, the latter has precedence.
[options.octaveOffset]number
0An integer to offset the octave by. This is only used when the input value is a note identifier.

Return Value

Returns: Note

Attributes: static

Throws:

  • TypeError The input could not be parsed to a note

.buildNoteArray(...)โ€‹

Since: 3.0.0

Converts an input value, which can be an unsigned integer (0-127), a note identifier, a Note object or an array of the previous types, to an array of Note objects.

Note objects are returned as is. For note numbers and identifiers, a Note object is created with the options specified. An error will be thrown when encountering invalid input.

Note: if both the attack and rawAttack options are specified, the later has priority. The same goes for release and rawRelease.

Parameters

Signature: buildNoteArray([notes], [options])

ParameterType(s)DefaultDescription
[notes]number
string
Note
Array.<number>
Array.<string>
Array.<Note>
[options]object
{}
[options.duration]number
InfinityThe number of milliseconds before the note should be explicitly stopped.
[options.attack]number
0.5The note's attack velocity as a float between 0 and 1. If you wish to use an integer between 0 and 127, use the rawAttack option instead. If both attack and rawAttack are specified, the latter has precedence.
[options.release]number
0.5The note's release velocity as a float between 0 and 1. If you wish to use an integer between 0 and 127, use the rawRelease option instead. If both release and rawRelease are specified, the latter has precedence.
[options.rawAttack]number
64The note's attack velocity as an integer between 0 and 127. If you wish to use a float between 0 and 1, use the release option instead. If both attack and rawAttack are specified, the latter has precedence.
[options.rawRelease]number
64The note's release velocity as an integer between 0 and 127. If you wish to use a float between 0 and 1, use the release option instead. If both release and rawRelease are specified, the latter has precedence.
[options.octaveOffset]number
0An integer to offset the octave by. This is only used when the input value is a note identifier.

Return Value

Returns: Array.<Note>

Attributes: static

Throws:

  • TypeError An element could not be parsed as a note.

.from7bitToFloat(...)โ€‹

Returns a number between 0 and 1 representing the ratio of the input value divided by 127 (7 bit). The returned value is restricted between 0 and 1 even if the input is greater than 127 or smaller than 0.

Passing Infinity will return 1 and passing -Infinity will return 0. Otherwise, when the input value cannot be converted to an integer, the method returns 0.

Parameters

Signature: from7bitToFloat(value)

ParameterType(s)DefaultDescription
valuenumber
A positive integer between 0 and 127 (inclusive)

Return Value

Returns: number

A number between 0 and 1 (inclusive)

Attributes: static

.fromFloatTo7Bit(...)โ€‹

Returns an integer between 0 and 127 which is the result of multiplying the input value by 127. The input value should be a number between 0 and 1 (inclusively). The returned value is restricted between 0 and 127 even if the input is greater than 1 or smaller than 0.

Passing Infinity will return 127 and passing -Infinity will return 0. Otherwise, when the input value cannot be converted to a number, the method returns 0.

Parameters

Signature: fromFloatTo7Bit(value)

ParameterType(s)DefaultDescription
valuenumber
A positive float between 0 and 1 (inclusive)

Return Value

Returns: number

A number between 0 and 127 (inclusive)

Attributes: static

.fromFloatToMsbLsb(...)โ€‹

Extracts 7bit MSB and LSB values from the supplied float.

Parameters

Signature: fromFloatToMsbLsb(value)

ParameterType(s)DefaultDescription
valuenumber
A float between 0 and 1

Return Value

Returns: Object

Attributes: static

.fromMsbLsbToFloat(...)โ€‹

Combines and converts MSB and LSB values (0-127) to a float between 0 and 1. The returned value is within between 0 and 1 even if the result is greater than 1 or smaller than 0.

Parameters

Signature: fromMsbLsbToFloat(msb, [lsb])

ParameterType(s)DefaultDescription
msbnumber
The most significant byte as a integer between 0 and 127.
[lsb]number
0The least significant byte as a integer between 0 and 127.

Return Value

Returns: number

A float between 0 and 1.

Attributes: static

.getCcNameByNumber(...)โ€‹

Returns the name of a control change message matching the specified number (0-127). Some valid control change numbers do not have a specific name or purpose assigned in the MIDI spec. In these cases, the method returns controllerXXX (where XXX is the number).

Parameters

Signature: getCcNameByNumber(number)

ParameterType(s)DefaultDescription
numbernumber
An integer (0-127) representing the control change message

Return Value

Returns: string or undefined

The matching control change name or undefined if no match was found.

Attributes: static

.getChannelModeByNumber(...)โ€‹

Since: 2.0.0

Returns the channel mode name matching the specified number. If no match is found, the function returns false.

Parameters

Signature: getChannelModeByNumber(number)

ParameterType(s)DefaultDescription
numbernumber
An integer representing the channel mode message (120-127)

Return Value

Returns: string or false

The name of the matching channel mode or false if no match could be found.

Attributes: static

.getNoteDetails(...)โ€‹

Since: 3.0.0

Given a proper note identifier (C#4, Gb-1, etc.) or a valid MIDI note number (0-127), this method returns an object containing broken down details about the specified note (uppercase letter, accidental and octave).

When a number is specified, the translation to note is done using a value of 60 for middle C (C4 = middle C).

Parameters

Signature: getNoteDetails(value)

ParameterType(s)DefaultDescription
valuestring
number
A note identifier A atring ("C#4", "Gb-1", etc.) or a MIDI note number (0-127).

Return Value

Returns: Object

Attributes: static

Throws:

  • TypeError Invalid note identifier

.getPropertyByValue(...)โ€‹

Returns the name of the first property of the supplied object whose value is equal to the one supplied. If nothing is found, undefined is returned.

Parameters

Signature: getPropertyByValue(object, value)

ParameterType(s)DefaultDescription
objectobject
The object to look for the property in.
value*
Any value that can be expected to be found in the object's properties.

Return Value

Returns: string or undefined

The name of the matching property or undefined if nothing is found.

Attributes: static

.guessNoteNumber(...)โ€‹

Since: 3.0.0

Returns a valid MIDI note number (0-127) given the specified input. The input usually is a string containing a note identifier ("C3", "F#4", "D-2", "G8", etc.). If an integer between 0 and 127 is passed, it will simply be returned as is (for convenience). Other strings will be parsed for integer value, if possible.

If the input is an identifier, the resulting note number is offset by the octaveOffset parameter. For example, if you pass in "C4" (note number 60) and the octaveOffset value is -2, the resulting MIDI note number will be 36.

Parameters

Signature: guessNoteNumber(input, octaveOffset)

ParameterType(s)DefaultDescription
inputstring
number
A string or number to extract the MIDI note number from.
octaveOffsetnumber
An integer to offset the octave by

Return Value

Returns: number or false

A valid MIDI note number (0-127) or false if the input could not successfully be parsed to a note number.

Attributes: static

.offsetNumber(...)โ€‹

Returns the supplied MIDI note number offset by the requested octave and semitone values. If the calculated value is less than 0, 0 will be returned. If the calculated value is more than 127, 127 will be returned. If an invalid offset value is supplied, 0 will be used.

Parameters

Signature: offsetNumber(number, octaveOffset, octaveOffset)

ParameterType(s)DefaultDescription
numbernumber
The MIDI note to offset as an integer between 0 and 127.
octaveOffsetnumber
0An integer to offset the note by (in octave)
octaveOffsetnumber
An integer to offset the note by (in semitones)

Return Value

Returns: number

An integer between 0 and 127

Attributes: static

Throws:

  • Error : Invalid note number

.sanitizeChannels(...)โ€‹

Since: 3.0.0

Returns a sanitized array of valid MIDI channel numbers (1-16). The parameter should be a single integer or an array of integers.

For backwards-compatibility, passing undefined as a parameter to this method results in all channels being returned (1-16). Otherwise, parameters that cannot successfully be parsed to integers between 1 and 16 are silently ignored.

Parameters

Signature: sanitizeChannels([channel])

ParameterType(s)DefaultDescription
[channel]number
Array.<number>
An integer or an array of integers to parse as channel numbers.

Return Value

Returns: Array.<number>

An array of 0 or more valid MIDI channel numbers.

Attributes: static

.toNoteIdentifier(...)โ€‹

Since: 3.0.0

Returns an identifier string representing a note name (with optional accidental) followed by an octave number. The octave can be offset by using the octaveOffset parameter.

Parameters

Signature: toNoteIdentifier(number, octaveOffset)

ParameterType(s)DefaultDescription
numbernumber
The MIDI note number to convert to a note identifier
octaveOffsetnumber
An offset to apply to the resulting octave

Return Value

Returns: string

Attributes: static

Throws:

  • RangeError Invalid note number
  • RangeError Invalid octaveOffset value

.toNoteNumber(...)โ€‹

Since: 3.0.0

Returns a MIDI note number matching the identifier passed in the form of a string. The identifier must include the octave number. The identifier also optionally include a sharp (#), a double sharp (##), a flat (b) or a double flat (bb) symbol. For example, these are all valid identifiers: C5, G4, D#-1, F0, Gb7, Eb-1, Abb4, B##6, etc.

When converting note identifiers to numbers, C4 is considered to be middle C (MIDI note number 60) as per the scientific pitch notation standard.

The resulting note number can be offset by using the octaveOffset parameter.

Parameters

Signature: toNoteNumber(identifier, [octaveOffset])

ParameterType(s)DefaultDescription
identifierstring
The identifier in the form of a letter, followed by an optional "#", "##", "b" or "bb" followed by the octave number. For exemple: C5, G4, D#-1, F0, Gb7, Eb-1, Abb4, B##6, etc.
[octaveOffset]number
0A integer to offset the octave by.

Return Value

Returns: number

The MIDI note number (an integer between 0 and 127).

Attributes: static

Throws:

  • RangeError Invalid 'octaveOffset' value
  • TypeError Invalid note identifier

.toTimestamp(...)โ€‹

Since: 3.0.0

Returns a valid timestamp, relative to the navigation start of the document, derived from the time parameter. If the parameter is a string starting with the "+" sign and followed by a number, the resulting timestamp will be the sum of the current timestamp plus that number. If the parameter is a positive number, it will be returned as is. Otherwise, false will be returned.

Parameters

Signature: toTimestamp([time])

ParameterType(s)DefaultDescription
[time]number
string
The time string (e.g. "+2000") or number to parse

Return Value

Returns: number or false

A positive number or false (if the time cannot be converted)

Attributes: static