Global

Methods

bar_and_beat_number_of_ontime(ontime, time_sigs_array) → {Array.<number>}

Given an ontime and a time-signature array (with ontimes included), this function returns the bar number and beat number of that ontime. Bar numbers are one-indexed, meaning the bar number of an ontime in an anacrusis is zero.

Parameters:
Name Type Description
ontime number

An ontime (time counting in crotchet beats starting from 0 for bar 1 beat 1) for which we want to know the corresponding bar and beat number.
time_sigs_array Array.<TimeSignature>

An array of time signatures.
Author:
  • Tom Collins
Returns:

An array whose first element is a bar number and whose second element is a beat number.

Type
Array.<number>
Example
var tsArr = [
  {
    "barNo": 1,
    "topNo": 4,
    "bottomNo": 4,
    "ontime": 0
  },
  {
    "barNo": 3,
    "topNo": 3,
    "bottomNo": 4,
    "ontime": 8
  }
];
bar_and_beat_number_of_ontime(11, tsArr);
→
[4, 1]

cardinality_score(P, Q) → {number}

This function calculates the difference between each pair of points in P and Q, sorts % by frequency of occurrence, and then returns the frequency of the most % frequently occurring difference vector, divided by the maximum of the % number of points in P and Q. If P is a translation of Q, then the % cardinality score is 1; if no two pairs of P points and Q points are % translations, then the cardinality score is zero; otherwise it is % somewhere between the two.

Parameters:
Name Type Description
P PointSet

A point set
Q PointSet

A point set
Author:
  • Tom Collins
Returns:

Output decimal and array

Type
number
Example
cardinality_score([[1, 1], [1, 3], [1, 4], [2, 2], [3, 1], [4, 1], [4, 4]], [[3, 4], [3, 6], [3, 7], [4, 2], [5, 4], [5, 5], [6, 7], [7, 1]])
→
[0.625, [2, 3]]

choose_one(arr, cdfopt) → {string|number|booelan}

This function selects an element at random from the input array and returns it. Optionally choices can be weighted by the parallel array cdf, which contains a cumulative distribution function.

Parameters:
Name Type Attributes Description
arr string | number | Array.<booelan>

An array.
cdf string | number | Array.<booelan> <optional>

An array.
Author:
  • Tom Collins
Returns:

An element from arr.

Type
string | number | booelan
Example
choose_one(["jp", "mn", "hc"]);
→
"hc"

copy_to_clipboard(arr, cdfopt) → {string|number|booelan}

This function calculates the sample standard deviation of an input array.

Parameters:
Name Type Attributes Description
arr number | Array.<booelan>

An array.
cdf string | number | Array.<booelan> <optional>

An array.
Author:
  • Tom Collins
Returns:

An element from arr.

Type
string | number | booelan
Example
copy_to_clipboard("Hi there!")
→
(Copies the text "Hi there!" to the clipboard.)

corr(x, y) → {number}

This function calculates the Pearson product-moment correlation coefficient between the input arrays x and y. It checks that the arrays are of the same length, but does not check that they each consist of numbers, nor for zero divisors (output NaN in both cases).

Parameters:
Name Type Description
x Array.<number>

An array
y Array.<number>

An array
Author:
  • Tom Collins
Returns:

in the range [-1, 1]

Type
number
Example
const x = [6, -4.2, 0]
const y = [0, 0.5, 1]
corr(x, y)
→
0.4274

count_rows(point_set, wght_idxopt) → {Object}

This function counts rows of the input point_set, weighted, if desired, by values in wght_idx.

Parameters:
Name Type Attributes Description
point_set PointSet

A point set
wght_idx number <optional>

The dimension of each point that should be used to weight the count. If left undefined, each occurrence of a point will increment the count of that point by 1.
Author:
  • Tom Collins and Christian Coulon
Returns:

[PointSet, number[]] An array whose first element is a PointSet (unique and lexicographically ascending version of the input), and whose second element is a (possibly weighted) count of those points in the input.

Type
Object
Example
var ps = [[64, 2], [65, 1], [67, 1], [67, 1]];
var w = 1;
count_rows(ps, w)
→
[
  [
    [64, 2], [65, 1], [67, 1]
  ],
  [
    2, // One occurrence of [64, 2] in input point set, with weight 2.
    1, // One occurrence of [65, 1] in input point set, with weight 1.
    2 // Two occurrences of [67, 1] in input point set, each with weight 1.
  ]
]

excess_kurtosis(arr) → {number}

This function calculates the sample excess kurtosis of an input array.

Parameters:
Name Type Description
arr Array.<number>

An array.
Author:
  • Tom Collins
Returns:

The calculated sample excess kurtosis.

Type
number
Example
excess_kurtosis([7.7, 10.5, 10.0, 13.3, 14.5, 19.1]);
→
-0.7508978

farey(n) → {Array.<number>}

This function returns the Farey sequence of order n.

Parameters:
Name Type Description
n number

Order of the Farey sequence
Author:
  • Tom Collins
Returns:

Farey sequence, deduplicated and in ascending order

Type
Array.<number>
Example
farey(6);
→
[0, 0.16667, 0.25, 0.33333, 0.5, 0.66667, 0.75, 0.83333, 1]

farey_quantise(D, Fnopt, dimopt) → {PointSet}

This function quantises time values in the input point set D by mapping their fractional parts to the closest member of the Farey sequence of order n (second argument). In a standard point set, time values are located in the first (ontime) and third (duration) indices of each point, hence the default argument for dim is [0, 3].

Parameters:
Name Type Attributes Description
D PointSet

A point set
Fn Array.<number> <optional>

Usually a Farey sequence
dim Array.<number> <optional>

An array of nonnegative integers indicating the indices of time values in the point set.
Author:
  • Tom Collins
Returns:

Quantised point set

Type
PointSet
Example
var ps = [
  [1.523, 60, 0.980],
  [2.873, 72, 0.192]
];
var fareySeq = [0, 0.5, 1];
var dimArr = [0, 2];
farey_quantise(ps, fareySeq, dimArr);
→
[
  [1.5, 60, 1],
  [3, 72, 0.5]
];

fifth_steps_mode(point_set, key_profiles, MNN_idxopt, dur_idxopt) → {Object}

This function is an implementation of the Krumhansl-Schmuckler key-finding algorithm. It returns a key estimate for the input points.

Parameters:
Name Type Attributes Default Description
point_set PointSet

A point set
key_profiles Array.<Array.<number>>

An array of arrays of 12-element vectors, where each vector is a cylic permutation of its neighbour. These are empirically derived weightings of the pitch-class content of each of the major and minor keys. There is a choice between krumhansl_and_kessler_key_profiles and aarden_key_profiles, which have different weightings.
MNN_idx number <optional>
 1

The dimension of MIDI note numbers in ps
dur_idx number <optional>
 2

The dimension of durations in ps
Author:
  • Tom Collins and Christian Coulon
Tutorials:
  • Tutorial: key-estimation-1
Returns:

[string, number, number, number] An array whose first element is a key name (e.g., "C major" for C major), whose second element is the maximum correlation value, whose third element is steps on the circle of fifths (e.g., -1 for F major), and whose fourth element is mode (e.g., 5 for minor/Aeolian). So for instance, a key estimate of A minor might have output ["A minor", .8, 3, 5].

Type
Object
Example
var ps = [
  [0, 56, 1],
  [0.5, 60, 1],
  [1, 58, 1],
  [1.5, 61, 1],
  [2, 60, 1],
  [2.5, 63, 1],
  [3, 61, 1],
  [3.5, 65, 1],
  [4, 63, 1],
  [4.5, 67, 1],
  [5, 65, 1],
  [5.5, 68, 1],
  [6, 67, 1],
  [6.5, 70, 1],
  [7, 68, 2]
];
fifth_steps_mode(ps, krumhansl_and_kessler_key_profiles)
→
[
  "Ab major", // Estimated key
  0.90135,    // Winning (maximal) correlation
  -4,         // Steps on the circle of fifths for Ab
  0           // Mode (major/Ionian)
]

get_parameter_by_name(name) → {string}

This function will return a string referring to a parameter value in the page URL, given the parameter name as its only argument.

Parameters:
Name Type Description
name string

Referring to a parameter name in the page URL.
Author:
  • Tom Collins
Returns:

Referring to the corresponding parameter value in the page URL.

Type
string
Example
Assuming a URL of https://something.com/index.html?r=0,3,0&c=0,2,3
    get_parameter_by_name("r")
→
"0,3,0"

harman_forward(segments, templates, lookup) → {Array.<Segment>}

This function labels input sets of notes (in segments), with chord names as provided in templates and lookup. Contiguous sets of notes may be combined and given the same label, if it is parsimonious to do so according to the algorithm. There is also some tolerance for non-chord tones. The function is an implementation of the forwards HarmAn algorithm of Pardo and Birmingham (2002).

Parameters:
Name Type Description
segments Array.<Segment>

An array of segments
templates Array.<Array.<number>>

An array of pitch-class sets.
lookup Array.<string>

An array of strings paraellel to templates, giving the interpretable label of each pitch-class set.
Author:
  • Tom Collins
Tutorials:
  • Tutorial: chord-labelling-1
Returns:

An array of segments where the additional, extra properties of name, index, and score have been populated, so as to (possibly combine) and label the chords from the input segments with names from templates and lookup.

Type
Array.<Segment>
Example
var ps = [
  [0, 45, 4], [0.5, 52, 3.5], [1, 59, 0.5], [1.5, 60, 2.5],
  [4, 41, 4], [4.5, 48, 3.5], [5, 55, 0.5], [5.5, 57, 2.5]
];
var seg = segment(ps);
harman_forward(seg, chord_templates_pbmin7ths, chord_lookup_pbmin7ths);
→
[
  {
    "ontime": 0,
    "offtime": 4.5,
    "points": [
                [0, 45, 51, 4, 0],
                [0.5, 52, 55, 3.5, 0],
                [1, 59, 59, 0.5, 0],
                [1.5, 60, 60, 2.5, 0],
                [4, 41, 49, 4, 0]
              ],
    "name": "A minor",
    "index": 33,
    "score": 6
  },
  {
    "ontime": 4.5,
    "offtime": 8,
    "points": [
                [4, 41, 49, 4, 0],
                [4.5, 48, 53, 3.5, 0],
                [5, 55, 57, 0.5, 0],
                [5.5, 57, 58, 2.5, 0]
              ],
    "name": "F major",
    "index": 5,
    "score": 6
  }
]

intersection(arr0, arr1, index) → {Array.<number>}

This function returns the intersection of two multidimensional numeric, arrays, assuming both are already in increasing lexicographic order to achieve O(n) computational complexity.

Parameters:
Name Type Description
arr0 Array.<number>

An array.
arr1 Array.<number>

An array.
index boolean | number

Indicates whether and which indices to record as belonging to the intersection. Takes value 0 if recording indices from arr0; value 1 if recording indices from arr0; true if recording indices from both; and false otherwise.
Author:
  • Tom Collins
Returns:

An array.

Type
Array.<number>
Example
intersection([[1, 4], [2, -2]], [[-2, 3], [2, -2], [4, 1]])
→
[[2, -2]]

median_skewness(arr) → {number}

This function calculates the median skewness (Pearson's second skewness coefficient) of a sample contained in an input array.

Parameters:
Name Type Description
arr Array.<number>

An array.
Author:
  • Tom Collins
Returns:

The calculated median skewness.

Type
number
Example
median_skewness([7.7, 10.5, 10.0, 13.3, 14.5, 19.1]);
→
0.5019952

ontime_of_bar_and_beat_number(bar, beat, time_sigs_array) → {number}

Given a bar number and beat number, and a time-signature array (with ontimes appended), this function returns the ontime of that bar and beat number.

Parameters:
Name Type Description
bar number

A bar number for which we want to know the corresponding ontime (time counting in crotchet beats starting from 0 for bar 1 beat 1).
beat number

A beat number for which we want to know the corresponding ontime (time counting in crotchet beats starting from 0 for bar 1 beat 1).
time_sigs_array Array.<TimeSignature>

An array of time signatures.
Author:
  • Tom Collins
Returns:

An ontime

Type
number
Example
var tsArr = [
  {
    "barNo": 1,
    "topNo": 4,
    "bottomNo": 4,
    "ontime": 0
  },
  {
    "barNo": 3,
    "topNo": 3,
    "bottomNo": 4,
    "ontime": 8
  }
];
ontime_of_bar_and_beat_number(4, 1, tsArr);
→
11

sample_without_replacement(arr, sampleSize) → {Array.<(number|string|boolean)>}

This function returns a random sample of elements from an input array, where the sampling is without replacement.

Parameters:
Name Type Description
arr Array.<(number|string|boolean)>

Input array
sampleSize number

Size of requested sample
Author:
  • Tom Collins
Returns:

Output array

Type
Array.<(number|string|boolean)>
Example
sample_without_replacement(["a", "b", "c"], 2);
→
["c", "a"]

skewness(arr) → {number}

This function calculates the sample skewness of an input array.

Parameters:
Name Type Description
arr Array.<number>

An array.
Author:
  • Tom Collins
Returns:

The calculated sample skewness.

Type
number
Example
skewness([7.7, 10.5, 10.0, 13.3, 14.5, 19.1]);
→
0.5251819

std(arr, cdfopt) → {string|number|booelan}

This function calculates the sample standard deviation of an input array.

Parameters:
Name Type Attributes Description
arr number | Array.<booelan>

An array.
cdf string | number | Array.<booelan> <optional>

An array.
Author:
  • Tom Collins
Returns:

An element from arr.

Type
string | number | booelan
Example
std([727.7, 1086.5, 1091.0, 1361.3, 1490.5, 1956.1]);
→
420.96

Type Definitions

Note

An object describing properties of a note in a musical composition.

Type:
  • Object
Properties:
Name Type Description
ontime number

The starting time of the note in crotchet (quarter-note) beats counting from 0 for bar (measure) 1 beat 1.
MNN number

The MIDI note number of the note (middle C = C4 = 60).
offtime number

The ending time of the note in crotchet (quarter-note) beats counting from 0 for bar (measure) 1 beat 1.
duration number

The duration of the note in crotchet (quarter-note) beats.
time number

The starting time of the note in seconds (also known as onset), taking into account tempo changes and expressive timing.
emit number

The ending time of the note in seconds (also known as offset), taking into account tempo changes and expressive timing.
durSec number

The duration of the note in seconds.

OnsetOntimeMap

An array consisting of onset-ontime pairs

Type:

OnsetOntimePair

A pair consisting of an onset and an ontime

Type:
  • Array.<number>

Point

A point

Type:
  • Array.<number>

PointSet

A point set

Type:

Segment

A minimal segment consists of the notes sounding between two partition points (Pardo & Birmingham, 2002). The partition points are the unique, sorted-ascending ontimes and offtimes in a song or piece. Contiguous minimal segments can be combined, hence "segment".

Type:
  • Object
Properties:
Name Type Attributes Description
ontime number

The partition point at which the segment begins.
offtime number

The partition point at which the segment ends.
points PointSet

The points corresponding to the notes sounding between the two partition points.
name string <optional>

An extra, optional property describing the segment, such as a chord label.
index number <optional>

An extra, optional property indexing the name property in some array of names.
score number <optional>

An extra, optional property rating the extent to which the name/label property applies to the content of points. Typically, a lower score would indicate lower applicability, and a higher score would indicate higher applicability.

Tempi

An array consisting of Tempo objects.

Type:

Tempo

An object describing properties of a tempo direction in a musical composition.

Type:
  • Object
Properties:
Name Type Description
ontime number

The starting time of the note in crotchet (quarter-note) beats counting from 0 for bar (measure) 1 beat 1.
bpm number

Beats per minute. As with ontime, which has units of crotchet (quarter-note) beats, we also measure our bpms in crotchet beats per minute.
tempo string

Indicates in words the speed at and/or manner in which something ought to be played.

TimeSignature

An object describing properties of a time signature in a musical composition.

Type:
  • Object
Properties:
Name Type Description
barNo number

Bar (measure) where the time signature begins.
topNo number

Top number in a time signature, denoting the number of beats in a bar.
bottomNo number

Takes the value 1, 2, 4, 8, 16, or 32. The bottom number in a time signature denotes the type of beat (1 for semibreve or whole note, 2 for minim or half note, etc.).
ontime number

Time measured in crotchet (quarter-note) beats at which the time signature begins.