Lookup for many MIDI specifications.
PromiseAllows to record audio blobs.
Handles incoming MIDI messages from a MIDI device.
PromiseRecords incoming MIDI messages from a MIDI device.
NoteGuitar note class that reflects MIDI properties but has absolute start and end times in seconds and information on how to play it.
NoteHarmonica note class that reflects MIDI properties but has absolute start and end times in seconds and information on how to play it.
Represents a parsed MIDI or MusicXML file in a uniform format.
Used by MusicPiece, should not be used directly
Tempo definition
Time signature definition
Key signature definition
Note class that reflects MIDI properties but has absolute start and end times in seconds.
This class represents an array of note objects. It can be used to simplify operations on a track.
Class that allows to represent pitch-bends from a MIDI file
Stores a sequence of pitches and provides some methods to simplify and manipulate it.
Class for storing recorded notes alongside meta information.
Map.<string, object>Maps internal drum names to MusicXML instrument names and note display
Map.<string, object>Contains patterns for exercises, such as scales
Map.<string, object>Contains patterns for exercises, such as scales TODO: find way to automatically compute patterns from scales, get scales from tonaljs
objectobjectMap.<number, number>Idea: Like in hierarchical clustering, take the most similar pair out of the set of all possible pairs repeatedly, until one array of items is empty.
Map.<Note, number>First matches GT to rec notes via priorityMatching, then computes the error for each GT note that has been matched using the same distance function. The Map will be undefined for GT notes that have not been matched, they can be considered missing in the recording.
numberComputes a distance (inverse similarity) of two notes, considering pitch, chroma, start, duration, and channel.
Array.<number>Returns the row and colum indices of the minimum value of the given matrix
Array.<Array.<number>>Takes a baseline pattern and moves it to the correct position on the fretboard
stringGenerates MusicXML text from a pattern
Array.<Array.<number>>Takes a baseline pattern and moves it to the correct position on the fretboard
stringGenerates MusicXML text from a pattern
Array.<Array.<number>>Takes a baseline pattern and moves it to the correct position on the fretboard
ArrayRepeats a pattern with or without alternating direction
stringGenerates MusicXML text from a pattern
Array.<number>Takes the ground truth and a single recording. Both gtNotes and recNotes must be sorted by note start time ascending.
Array.<string>Array.<string>numbernumbernumbernumbernumbernumberComputes the number of notes
numberComputes played duration
numberComputes the number of notes played per second
numberComputes the number of notes played per relative time (beat)
Array.<object>Computes the number of different notes used in different modi.
numberComputes the ratio of notes that are in the given set. Can be used for checking how many notes that were played are part of a musical scale, by passing the notes of this scale as set.
objectComputes the mean and variance of played pitches
Array.<number>Computes the min and max pitch
objectComputes the mean and variance of played intervals
objectComputes the mean and variance of played dynamics
objectComputes the mean and variance of played dynamics
objectComputes the mean and variance of onset (start time) differences between consecutive notes.
numberComputs the ratio of notes for which one string (or more) where skipped
between the one before and the current note.
The skipped parameter set the minimum amount of strings between the two
notes, e.g., going from string 1 to 3 means that one (string 2) was skipped.
numberComputs the ratio of notes for which one fret (or more) where skipped between
the one before and the current note.
The skipped parameter set the minimum amount of fret between the two
notes, e.g., going from fret 1 to 3 means that one (fret 2) was skipped.
Array.<object>Counts how often harmonies of different sizes occur
numberDetermines the ratio of single notes to multi-note harmonies
Array.<number>Computes the pitch intervals between consecutive notes
Array.<number>Computes the start time differences between consecutive notes
objectCompresses a sequence by detecting immediately repeating subsequences hierarchically. Optimal result but high performance complexity.
Array.<object>Finds all immediate repetitions in a given sequence.
ArrayRestores the original array/sequence from the compressed hierarchy.
ArrayReturns the summary of a hierachy, leaving out information about repetitions.
stringFormats a compressed hierarchy into a readable string, for example: "1222333222333" => "1 (2x (3x 2) (3x 3))"
numberCalculates the compression rate in [0, 1] for a result of compress().
Map.<string, number>Calculates all n-grams with a specified length
Map.<string, object>Calculates all n-grams with a specified length
Simplifies each object in an array by copying only some keys and their values
ObjectGiven a file name (without extension), this function will read a .mid and a .musicxml file and parse both to a MusicPiece before returning those.
numberDetermines the perceptual lightness of an HTML color
stringDetermines the average of mutliple given colors
stringSets a color's opacity. Does not support colors in rgba format.
stringSets a color's saturation. Does not support colors in rgba format.
NoteArray](#NoteArray)
* [.alignNoteArrays2(gt, rec)](#module_Alignment.alignNoteArrays2) ⇒ [NoteArray](#NoteArray)
* [.alignNoteArrays3(gt, rec)](#module_Alignment.alignNoteArrays3) ⇒ [NoteArray](#NoteArray)
* [.testAlignment()](#module_Alignment.testAlignment)
* [.alignmentBenchmark()](#module_Alignment.alignmentBenchmark)
* _inner_
* [~alignmentForce(a, b)](#module_Alignment..alignmentForce) ⇒ number
### Alignment.alignNoteArrays(gt, rec) ⇒ [NoteArray](#NoteArray)
Given two NoteArrays, shift the second one in time such that they are aligned
**Kind**: static method of [Alignment](#module_Alignment)
**Returns**: [NoteArray](#NoteArray) - an aligned copy of b
**Todo**
- [ ] use https://en.wikipedia.org/wiki/Smith%E2%80%93Waterman_algorithm
to find note alignment, then only use those for force calculation
| Param | Type | Description |
| --- | --- | --- |
| gt | [NoteArray](#NoteArray) | a NoteArray, e.g. the ground truth |
| rec | [NoteArray](#NoteArray) | a NoteArray to align to a |
### Alignment.alignNoteArrays2(gt, rec) ⇒ [NoteArray](#NoteArray)
Given two NoteArrays, shift the second one in time such that they are aligned
**Kind**: static method of [Alignment](#module_Alignment)
**Returns**: [NoteArray](#NoteArray) - an aligned copy of b
| Param | Type | Description |
| --- | --- | --- |
| gt | [NoteArray](#NoteArray) | a NoteArray, e.g. the ground truth |
| rec | [NoteArray](#NoteArray) | a NoteArray to align to a |
### Alignment.alignNoteArrays3(gt, rec) ⇒ [NoteArray](#NoteArray)
Given two NoteArrays, shift the second one in time such that they are aligned
**Kind**: static method of [Alignment](#module_Alignment)
**Returns**: [NoteArray](#NoteArray) - an aligned copy of b
**Todo**
- [ ] use median instead of average?
| Param | Type | Description |
| --- | --- | --- |
| gt | [NoteArray](#NoteArray) | a NoteArray, e.g. the ground truth |
| rec | [NoteArray](#NoteArray) | a NoteArray to align to a |
### Alignment.testAlignment()
Test function
**Kind**: static method of [Alignment](#module_Alignment)
**Todo**
- [ ] move to test
### Alignment.alignmentBenchmark()
**Kind**: static method of [Alignment](#module_Alignment)
**Todo**
- [ ] Benchmark different aligment functions on a randomly generated test set
This allows to check the calculated alignment against a known ground truth
### Alignment~alignmentForce(a, b) ⇒ number
Calculates the mean difference between all notes in a and the nearest same-
pitched notes in b
**Kind**: inner method of [Alignment](#module_Alignment)
**Returns**: number - mean time difference
| Param | Type | Description |
| --- | --- | --- |
| a | [Array.<Note>](#Note) | array with notes |
| b | [Array.<Note>](#Note) | array with notes |
## DiffAlignment
* [DiffAlignment](#module_DiffAlignment)
* [.alignRecordingToBestFit(gtNotes, recording, binSize)](#module_DiffAlignment.alignRecordingToBestFit) ⇒ [Recording](#Recording)
* [.alignRecordingSectionsToBestFit(gtNotes, recording, binSize, gapDuration, gapMode)](#module_DiffAlignment.alignRecordingSectionsToBestFit) ⇒ [Recording](#Recording)
* [.alignGtAndRecToMinimizeDiffError(gtNotes, recNotes, binSize)](#module_DiffAlignment.alignGtAndRecToMinimizeDiffError) ⇒ Array.<object>
* [.activationMap(allNotes, binSize)](#module_DiffAlignment.activationMap) ⇒ Map
* [.agreement(gtActivations, recActivations, offset)](#module_DiffAlignment.agreement) ⇒ number
### DiffAlignment.alignRecordingToBestFit(gtNotes, recording, binSize) ⇒ [Recording](#Recording)
Aligns the recording to the best fitting position of the ground truth
**Kind**: static method of [DiffAlignment](#module_DiffAlignment)
**Returns**: [Recording](#Recording) - aligned recording
| Param | Type | Description |
| --- | --- | --- |
| gtNotes | [Array.<Note>](#Note) | ground truth notes |
| recording | [Recording](#Recording) | a Recording object |
| binSize | number | time bin size in milliseconds |
### DiffAlignment.alignRecordingSectionsToBestFit(gtNotes, recording, binSize, gapDuration, gapMode) ⇒ [Recording](#Recording)
Splits the recording at gaps > gapDuration and then aligns each section to
the best fitting position of the ground truth.
**Kind**: static method of [DiffAlignment](#module_DiffAlignment)
**Returns**: [Recording](#Recording) - aligned recording
| Param | Type | Description |
| --- | --- | --- |
| gtNotes | [Array.<Note>](#Note) | ground truth notes |
| recording | [Recording](#Recording) | a Recording object |
| binSize | number | time bin size in milliseconds |
| gapDuration | number | duration of seconds for a gap to be used as segmenting time |
| gapMode | 'start-start' \| 'end-start' | gaps can either be considered as the maximum time between two note's starts or the end of the first and the start of the second note |
### DiffAlignment.alignGtAndRecToMinimizeDiffError(gtNotes, recNotes, binSize) ⇒ Array.<object>
Global alignment.
Returns an array with matches sorted by magnitude of agreement.
The offsetMilliseconds value describes at what time the first note of the
recording should start.
Goal: Know which part of ground truth (GT) was played in recording (rec)
Assumptions:
- Rec has same tempo as GT
- Rec does not start before GT
- Rec does not repeat something that is not repeated in the GT
- Rec does not have gaps
Ideas:
- Brute-force
- Sliding window
- Using diff between time-pitch matrix of GT and rec
- Only compute agreement (correct diff part) for the current overlap
- For each time position save the agreement magnitude
- Optionally: repeat around local maxima with finer binSize
**Kind**: static method of [DiffAlignment](#module_DiffAlignment)
**Returns**: Array.<object> - best offsets with agreements
| Param | Type | Description |
| --- | --- | --- |
| gtNotes | [Array.<Note>](#Note) | ground truth notes |
| recNotes | [Array.<Note>](#Note) | recorded notes |
| binSize | number | time bin size in milliseconds |
### DiffAlignment.activationMap(allNotes, binSize) ⇒ Map
Returns an activation map, that maps pitch to an array of time bins.
Each bin contains a 0 when there is no note or a 1 when there is one.
**Kind**: static method of [DiffAlignment](#module_DiffAlignment)
**Returns**: Map - activation map
| Param | Type | Description |
| --- | --- | --- |
| allNotes | [Array.<Note>](#Note) | notes |
| binSize | number | time bin size in milliseconds |
### DiffAlignment.agreement(gtActivations, recActivations, offset) ⇒ number
Given two activation maps, simply counts the number of bins [pitch, time]
where both have a 1, so an acitve note
GT must be longer than rec
**Kind**: static method of [DiffAlignment](#module_DiffAlignment)
**Returns**: number - agreement
**Todo**
- [ ] also count common 0s?
| Param | Type | Description |
| --- | --- | --- |
| gtActivations | Map | see activationMap() |
| recActivations | Map | see activationMap() |
| offset | number | offset for activation2 when comparing |
## Chords
* [Chords](#module_Chords)
* [.detectChordsByExactStart(notes)](#module_Chords.detectChordsByExactStart) ⇒ Array.<Array.<Note>>
* [.detectChordsBySimilarStart(notes, threshold)](#module_Chords.detectChordsBySimilarStart) ⇒ Array.<Array.<Note>>
* [.detectChordsByOverlap(notes, sortByPitch)](#module_Chords.detectChordsByOverlap) ⇒ Array.<Array.<Note>>
* [.getChordType(notes)](#module_Chords.getChordType) ⇒ string
* [.getChordName(notes)](#module_Chords.getChordName) ⇒ Array.<string>
### Chords.detectChordsByExactStart(notes) ⇒ Array.<Array.<Note>>
Detects chords as those notes that have the exact same start time, only works
for ground truth (since recordings are not exact)
Does only work if ground truth is aligned! TuxGuitar produces unaligned MIDI.
**Kind**: static method of [Chords](#module_Chords)
**Returns**: Array.<Array.<Note>> - array of chord arrays
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
### Chords.detectChordsBySimilarStart(notes, threshold) ⇒ Array.<Array.<Note>>
Detects chords by taking a note as new chord then adding all notes close
after it to the chord, until the next note is farther away than the given
`threshold`. Then, the next chord is started with this note.
**Kind**: static method of [Chords](#module_Chords)
**Returns**: Array.<Array.<Note>> - chords
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| threshold | number | threshold |
### Chords.detectChordsByOverlap(notes, sortByPitch) ⇒ Array.<Array.<Note>>
Detects chords, by simply looking for notes that overlap each other in time.
Example:
=======
=========
========
Important: Notes must be sorted by start time for this to work correctly.
**Kind**: static method of [Chords](#module_Chords)
**Returns**: Array.<Array.<Note>> - array of chord arrays
**Todo**
- [ ] not used yet
- [ ] optional minimum overlap ratio
- [ ] new definition of chord? i.e. notes have to start 'together'
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | array of Note objects |
| sortByPitch | boolean | sort chords by pitch? (otherwise sorted by note start time) |
### Chords.getChordType(notes) ⇒ string
Returns chord type, e.g. 'Major', 'Diminished', ...
Important: Notes must be sorted by pitch ascending
**Kind**: static method of [Chords](#module_Chords)
**Returns**: string - chord type
**Todo**
- [ ] some chords might be multiple types
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes (sorted by pitch asc.) |
### Chords.getChordName(notes) ⇒ Array.<string>
https://github.com/tonaljs/tonal/tree/master/packages/chord
Detected chords can be used with https://github.com/tonaljs/tonal/tree/master/packages/chord-type
**Kind**: static method of [Chords](#module_Chords)
**Returns**: Array.<string> - possible chord types
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## comparison/ErrorClassifier
* [comparison/ErrorClassifier](#module_comparison/ErrorClassifier)
* _static_
* [.classifyErrors(gtNotes, recNotes, groupBy, threshold)](#module_comparison/ErrorClassifier.classifyErrors) ⇒ Array.<NoteWithState>
* [.separateMissed(classifiedNotes)](#module_comparison/ErrorClassifier.separateMissed) ⇒ Object
* _inner_
* [~setOrAdd(map, key, value)](#module_comparison/ErrorClassifier..setOrAdd)
* [~hasAtLeastOne(map, key)](#module_comparison/ErrorClassifier..hasAtLeastOne) ⇒ boolean
### comparison/ErrorClassifier.classifyErrors(gtNotes, recNotes, groupBy, threshold) ⇒ Array.<NoteWithState>
Compares a single recording to a ground truth and labels notes as missing,
extra, early/late, or short/long
**Kind**: static method of [comparison/ErrorClassifier](#module_comparison/ErrorClassifier)
**Returns**: Array.<NoteWithState> - classified notes
**Todo**
- [ ] generalize to channel/pitch instead of string and fret?
| Param | Type | Description |
| --- | --- | --- |
| gtNotes | [Array.<Note>](#Note) \| [Array.<GuitarNote>](#GuitarNote) | ground truth notes |
| recNotes | [Array.<Note>](#Note) \| [Array.<GuitarNote>](#GuitarNote) | recordings notes |
| groupBy | string | attribute to group notes by |
| threshold | number | time threshold for same-ness |
### comparison/ErrorClassifier.separateMissed(classifiedNotes) ⇒ Object
Separates classified GT and rec notes
**Kind**: static method of [comparison/ErrorClassifier](#module_comparison/ErrorClassifier)
**Returns**: Object - separated notes
| Param | Type | Description |
| --- | --- | --- |
| classifiedNotes | Array.<NoteWithState> | classified notes |
### comparison/ErrorClassifier~setOrAdd(map, key, value)
**Kind**: inner method of [comparison/ErrorClassifier](#module_comparison/ErrorClassifier)
| Param | Type | Description |
| --- | --- | --- |
| map | Map | map |
| key | \* | key |
| value | \* | value |
### comparison/ErrorClassifier~hasAtLeastOne(map, key) ⇒ boolean
**Kind**: inner method of [comparison/ErrorClassifier](#module_comparison/ErrorClassifier)
**Returns**: boolean - true if map.get(key).size > 0
| Param | Type | Description |
| --- | --- | --- |
| map | Map | map |
| key | \* | key |
## comparison/Matching
* [comparison/Matching](#module_comparison/Matching)
* [.matchGtAndRecordingNotes(recNotes, gtNotes)](#module_comparison/Matching.matchGtAndRecordingNotes) ⇒ Map
* [.matchGtAndMultipleRecordings(recordings, gtNotes)](#module_comparison/Matching.matchGtAndMultipleRecordings) ⇒ Map
* [.getMultiMatchingErrorPerNote(multiMatching, errorThreshold)](#module_comparison/Matching.getMultiMatchingErrorPerNote) ⇒ Map
* [.getMatchingError(matching, addPenalty, missPenalty, timingPenalty, timeThreshold)](#module_comparison/Matching.getMatchingError) ⇒ object
* [.getMatchingSection(matching, start, end)](#module_comparison/Matching.getMatchingSection) ⇒ Map
* [.getMatchingSliceError(matching, start, end, addPenalty, missPenalty, timingPenalty)](#module_comparison/Matching.getMatchingSliceError) ⇒ object
### comparison/Matching.matchGtAndRecordingNotes(recNotes, gtNotes) ⇒ Map
For one recording, separately for each pitch,
matches each recorded note to its closest ground truth note.
If there are multiple matches, the best (smallest time difference)
will be kept and others will be regarded as additional notes.
Ground truth notes without match will be regarded as missing notes.
Result format (separated by pitch in a Map):
Map:pitch->{
gtRecMap matched rec. note for each GT note Map:gtNoteStart->recNote,
additionalNotes: rec. notes without matched GT note
missingNotes: GT notes without matched rec. note
gtNotes: all GT notes
}
**Kind**: static method of [comparison/Matching](#module_comparison/Matching)
**Returns**: Map - result
**Todo**
- [ ] add max distance?
| Param | Type | Description |
| --- | --- | --- |
| recNotes | [Array.<Note>](#Note) | recorded notes of a single recording |
| gtNotes | [Array.<Note>](#Note) | ground truth notes |
### comparison/Matching.matchGtAndMultipleRecordings(recordings, gtNotes) ⇒ Map
Matches all recorded notes from multiple recordings to the nearest
ground truth (GT) note.
Contrary to the matching created by matchGtAndRecordingNotes()
missing and additional notes are not considered, so multiple notes
from a single recording can be matched to the same GT note.
Result format:
Map:pitch->Map:gtStart->arrayOfMatchedRecNotes
**Kind**: static method of [comparison/Matching](#module_comparison/Matching)
**Returns**: Map - matching
| Param | Type | Description |
| --- | --- | --- |
| recordings | [Array.<Recording>](#Recording) | recordings |
| gtNotes | [Array.<Note>](#Note) | ground truth notes |
### comparison/Matching.getMultiMatchingErrorPerNote(multiMatching, errorThreshold) ⇒ Map
Calculates (for each pitch) the average error for each GT note (averaged
over all matched notes in the recordings),
as well as the maximum of all those average errors.
GT notes that have no matched recorded notes will have an error of 0.
**Kind**: static method of [comparison/Matching](#module_comparison/Matching)
**Returns**: Map - error summary Map:pitch->{gtErrorMap, maxError},
gtErrorMap is Map:gtStart->error (error is average over all time
differences between the GT note and matched recNotes)
| Param | Type | Description |
| --- | --- | --- |
| multiMatching | Map | matching with a GT and multiple recordings |
| errorThreshold | number | number seconds of deviation above which to exclude an error |
### comparison/Matching.getMatchingError(matching, addPenalty, missPenalty, timingPenalty, timeThreshold) ⇒ object
Calculates the error of a matching by applying penalties and summing up
**Kind**: static method of [comparison/Matching](#module_comparison/Matching)
**Returns**: object - errors by category
| Param | Type | Description |
| --- | --- | --- |
| matching | Map | a matching created by matchGtAndRecordingNotes |
| addPenalty | number | penalty for each additonal note |
| missPenalty | number | penalty for each missing note |
| timingPenalty | number | penalty for note timing differences in seconds |
| timeThreshold | number | timing errors below it (absolute) are ignored |
### comparison/Matching.getMatchingSection(matching, start, end) ⇒ Map
Cuts a section from a matching by filtering on the start times
of ground truth, missing, and additonal notes
**Kind**: static method of [comparison/Matching](#module_comparison/Matching)
**Returns**: Map - section of matching
| Param | Type | Description |
| --- | --- | --- |
| matching | Map | matching |
| start | number | start time (inclusive) |
| end | number | end time (exclusive) |
### comparison/Matching.getMatchingSliceError(matching, start, end, addPenalty, missPenalty, timingPenalty) ⇒ object
Shortcut for getMatchingSection and getMatchingError,
see them for parameter details.
**Kind**: static method of [comparison/Matching](#module_comparison/Matching)
**Returns**: object - error by category
| Param | Type | Description |
| --- | --- | --- |
| matching | Map | matching |
| start | number | start time (inclusive) |
| end | number | end time (exclusive) |
| addPenalty | number | penalty for each additonal note |
| missPenalty | number | penalty for each missing note |
| timingPenalty | number | penalty for note timing differences in seconds |
## comparison/Similarity
* [comparison/Similarity](#module_comparison/Similarity)
* _static_
* [.getSimilarParts(track, selectedInterval, stride, threshold, secondsPerBin, distance)](#module_comparison/Similarity.getSimilarParts) ⇒ object
* [.getTrackSimilarity(discrA, discrB, distance)](#module_comparison/Similarity.getTrackSimilarity) ⇒ number
* [.discretizeTime(track, secondsPerBin)](#module_comparison/Similarity.discretizeTime) ⇒ Map
* _inner_
* [~countActiveNoteBins(binArray)](#module_comparison/Similarity..countActiveNoteBins) ⇒ number
* [~sliceDiscretizedTrack(trackMap, startBin, endBin)](#module_comparison/Similarity..sliceDiscretizedTrack) ⇒ Map
* [~euclideanDistanceSquared(A, B)](#module_comparison/Similarity..euclideanDistanceSquared) ⇒ number
* [~neirestNeighborDistance(A, B)](#module_comparison/Similarity..neirestNeighborDistance) ⇒ number
### comparison/Similarity.getSimilarParts(track, selectedInterval, stride, threshold, secondsPerBin, distance) ⇒ object
Given a track, a selected time interval and a threshold,
this function searches for parts in the track that are
similar to the selection.
It uses a sliding window with the size of the selection
and a stride given as argument.
**Kind**: static method of [comparison/Similarity](#module_comparison/Similarity)
**Returns**: object - similar parts
| Param | Type | Description |
| --- | --- | --- |
| track | [Array.<Note>](#Note) | array of Note objects |
| selectedInterval | Array.<number> | [startTime, endTime] in seconds |
| stride | number | stride for the sliding window in number of bins |
| threshold | number | distance threshold below which parts are considered similar |
| secondsPerBin | number | time bin size in seconds |
| distance | string | one of: 'dtw', 'euclidean', 'nearest' |
### comparison/Similarity.getTrackSimilarity(discrA, discrB, distance) ⇒ number
Uses calculates the distance between
two discretized tracks, for each pitch separately.
Pitch-wise distances are averaged and a penalty is added to the distance
for pitches that are not occuring in both tracks
**Kind**: static method of [comparison/Similarity](#module_comparison/Similarity)
**Returns**: number - distance
**See**: https://github.com/GordonLesti/dynamic-time-warping
| Param | Type | Description |
| --- | --- | --- |
| discrA | Map | discretized track |
| discrB | Map | discretized track |
| distance | string | one of: 'euclidean', 'nearest' |
### comparison/Similarity.discretizeTime(track, secondsPerBin) ⇒ Map
- Normalizes Note times to be between 0 and (maxTime - minTime),
- discretizes the start and end time by using Math.round to get
the closest time bin (beat) and
- Creates one array for each pitch, where each entry contains
either a 0 (no note at that time bin) or a 1 (note at that time bin)
**Kind**: static method of [comparison/Similarity](#module_comparison/Similarity)
**Returns**: Map - pitch to binArray
| Param | Type | Description |
| --- | --- | --- |
| track | [Array.<Note>](#Note) | an array of Note objects |
| secondsPerBin | number | time bin size in seconds |
### comparison/Similarity~countActiveNoteBins(binArray) ⇒ number
Counts the occurence of 1 in an array
**Kind**: inner method of [comparison/Similarity](#module_comparison/Similarity)
**Returns**: number - occurence of 1
| Param | Type | Description |
| --- | --- | --- |
| binArray | Array.<number> | array |
### comparison/Similarity~sliceDiscretizedTrack(trackMap, startBin, endBin) ⇒ Map
Slices bins out of a discretices track.
This is done for each pitch separately
**Kind**: inner method of [comparison/Similarity](#module_comparison/Similarity)
**Returns**: Map - map with sliced arrays
| Param | Type | Description |
| --- | --- | --- |
| trackMap | Map | Map pitch->binArray |
| startBin | number | index of first bin |
| endBin | number | index of last bin |
### comparison/Similarity~euclideanDistanceSquared(A, B) ⇒ number
Returns sum_{i=0}^{N-1}{(a_i-b_i)^2},
i.e. Euclidean distance but without square root
**Kind**: inner method of [comparison/Similarity](#module_comparison/Similarity)
**Returns**: number - Euclidean distance
| Param | Type | Description |
| --- | --- | --- |
| A | Array.<number> | an array |
| B | Array.<number> | another array |
### comparison/Similarity~neirestNeighborDistance(A, B) ⇒ number
Given two arrays containing 1s and 0s, this algorithm
goes through all bins and for each bin where one array
has a 1 and the other a 0, it searches for the closest 1
next to the 0.
The distance is then added to the global distance.
**Kind**: inner method of [comparison/Similarity](#module_comparison/Similarity)
**Returns**: number - nearest neighbor distance
| Param | Type | Description |
| --- | --- | --- |
| A | Array.<number> | an array |
| B | Array.<number> | another array |
## comparison/SimilarSections
* [comparison/SimilarSections](#module_comparison/SimilarSections)
* [.findSimilarNoteSections(notes, startTime, endTime, threshold)](#module_comparison/SimilarSections.findSimilarNoteSections) ⇒ Array.<object>
* [.findSimilarStringSections(dataString, searchString, threshold)](#module_comparison/SimilarSections.findSimilarStringSections) ⇒ Array.<object>
### comparison/SimilarSections.findSimilarNoteSections(notes, startTime, endTime, threshold) ⇒ Array.<object>
Turns an array of notes into a string to perform pattern matching search for similar
patterns.
**Kind**: static method of [comparison/SimilarSections](#module_comparison/SimilarSections)
**Returns**: Array.<object> - {index, distance, startTime, endTime}
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes, must be sorted by Note.start |
| startTime | number | start time of the section to search |
| endTime | number | end time for the section to search |
| threshold | number | threshold for normalized Levenshtein distance in [0, 1] |
### comparison/SimilarSections.findSimilarStringSections(dataString, searchString, threshold) ⇒ Array.<object>
Finds similar sections in a string via Levenshtein distance
**Kind**: static method of [comparison/SimilarSections](#module_comparison/SimilarSections)
**Returns**: Array.<object> - {index, distance}
| Param | Type | Description |
| --- | --- | --- |
| dataString | stringArray | they string to search in |
| searchString | stringArray | the string to search for |
| threshold | number | threshold for normalized Levenshtein distance in [0, 1] |
## instruments/StringedFingering
**Todo**
- [ ] unfinished
- [ ] not tested
* [instruments/StringedFingering](#module_instruments/StringedFingering)
* [.FretboardPosition](#module_instruments/StringedFingering.FretboardPosition)
* [new exports.FretboardPosition(string, fret)](#new_module_instruments/StringedFingering.FretboardPosition_new)
* [.moveBy(string, fret)](#module_instruments/StringedFingering.FretboardPosition+moveBy)
* [.isValid(maxString, maxFret)](#module_instruments/StringedFingering.FretboardPosition+isValid) ⇒ boolean
* [.equals(otherFretboardPosition)](#module_instruments/StringedFingering.FretboardPosition+equals) ⇒ boolean
* [.toString()](#module_instruments/StringedFingering.FretboardPosition+toString) ⇒ string
* [.clone()](#module_instruments/StringedFingering.FretboardPosition+clone) ⇒ FretboardPosition
* [.difference(otherFretboardPosition)](#module_instruments/StringedFingering.FretboardPosition+difference) ⇒ object
* [.HandPose](#module_instruments/StringedFingering.HandPose)
* [new exports.HandPose(fingerPositions)](#new_module_instruments/StringedFingering.HandPose_new)
* [.moveFingerTo(index, newPosition)](#module_instruments/StringedFingering.HandPose+moveFingerTo)
* [.liftFinger(index)](#module_instruments/StringedFingering.HandPose+liftFinger)
* [.moveFingerBy(index, string, fret)](#module_instruments/StringedFingering.HandPose+moveFingerBy)
* [.moveHandBy(string, fret)](#module_instruments/StringedFingering.HandPose+moveHandBy)
* [.isValid(maxString, maxFret)](#module_instruments/StringedFingering.HandPose+isValid) ⇒ boolean
* [.euqals(otherHandPose)](#module_instruments/StringedFingering.HandPose+euqals) ⇒ boolean
* [.toString()](#module_instruments/StringedFingering.HandPose+toString) ⇒ string
* [.clone()](#module_instruments/StringedFingering.HandPose+clone) ⇒ HandPose
* [.difference(otherHandPose)](#module_instruments/StringedFingering.HandPose+difference) ⇒ Array.<object>
* [.costOfMovement(otherHandPose)](#module_instruments/StringedFingering.HandPose+costOfMovement) ⇒ number
### instruments/StringedFingering.FretboardPosition
Represents a positon as {string, fret}
**Kind**: static class of [instruments/StringedFingering](#module_instruments/StringedFingering)
* [.FretboardPosition](#module_instruments/StringedFingering.FretboardPosition)
* [new exports.FretboardPosition(string, fret)](#new_module_instruments/StringedFingering.FretboardPosition_new)
* [.moveBy(string, fret)](#module_instruments/StringedFingering.FretboardPosition+moveBy)
* [.isValid(maxString, maxFret)](#module_instruments/StringedFingering.FretboardPosition+isValid) ⇒ boolean
* [.equals(otherFretboardPosition)](#module_instruments/StringedFingering.FretboardPosition+equals) ⇒ boolean
* [.toString()](#module_instruments/StringedFingering.FretboardPosition+toString) ⇒ string
* [.clone()](#module_instruments/StringedFingering.FretboardPosition+clone) ⇒ FretboardPosition
* [.difference(otherFretboardPosition)](#module_instruments/StringedFingering.FretboardPosition+difference) ⇒ object
#### new exports.FretboardPosition(string, fret)
| Param | Type | Description |
| --- | --- | --- |
| string | number | string |
| fret | number | fret |
#### fretboardPosition.moveBy(string, fret)
Moves the positon by string and fret
**Kind**: instance method of [FretboardPosition](#module_instruments/StringedFingering.FretboardPosition)
| Param | Type | Description |
| --- | --- | --- |
| string | number | string |
| fret | number | fret |
#### fretboardPosition.isValid(maxString, maxFret) ⇒ boolean
Checks whether this position is valid
**Kind**: instance method of [FretboardPosition](#module_instruments/StringedFingering.FretboardPosition)
**Returns**: boolean - true iff valid
| Param | Type | Description |
| --- | --- | --- |
| maxString | number | number of strings -1 |
| maxFret | number | number of frets |
#### fretboardPosition.equals(otherFretboardPosition) ⇒ boolean
Returns true iff this and another FretboardPosition are equal
**Kind**: instance method of [FretboardPosition](#module_instruments/StringedFingering.FretboardPosition)
**Returns**: boolean - true iff equal
| Param | Type | Description |
| --- | --- | --- |
| otherFretboardPosition | FretboardPosition | another FretboardPosition |
#### fretboardPosition.toString() ⇒ string
String representation
**Kind**: instance method of [FretboardPosition](#module_instruments/StringedFingering.FretboardPosition)
**Returns**: string - string representation
#### fretboardPosition.clone() ⇒ FretboardPosition
**Kind**: instance method of [FretboardPosition](#module_instruments/StringedFingering.FretboardPosition)
**Returns**: FretboardPosition - clone
#### fretboardPosition.difference(otherFretboardPosition) ⇒ object
Returns (other - this), i.e. how you need to move this to get to other
**Kind**: instance method of [FretboardPosition](#module_instruments/StringedFingering.FretboardPosition)
**Returns**: object - difference in {string, fret}
| Param | Type | Description |
| --- | --- | --- |
| otherFretboardPosition | FretboardPosition | another FretboardPosition |
### instruments/StringedFingering.HandPose
Represents a hand pose, for each of the 10 fingers with a FretboardPosition
or null, if the finger is not used
**Kind**: static class of [instruments/StringedFingering](#module_instruments/StringedFingering)
* [.HandPose](#module_instruments/StringedFingering.HandPose)
* [new exports.HandPose(fingerPositions)](#new_module_instruments/StringedFingering.HandPose_new)
* [.moveFingerTo(index, newPosition)](#module_instruments/StringedFingering.HandPose+moveFingerTo)
* [.liftFinger(index)](#module_instruments/StringedFingering.HandPose+liftFinger)
* [.moveFingerBy(index, string, fret)](#module_instruments/StringedFingering.HandPose+moveFingerBy)
* [.moveHandBy(string, fret)](#module_instruments/StringedFingering.HandPose+moveHandBy)
* [.isValid(maxString, maxFret)](#module_instruments/StringedFingering.HandPose+isValid) ⇒ boolean
* [.euqals(otherHandPose)](#module_instruments/StringedFingering.HandPose+euqals) ⇒ boolean
* [.toString()](#module_instruments/StringedFingering.HandPose+toString) ⇒ string
* [.clone()](#module_instruments/StringedFingering.HandPose+clone) ⇒ HandPose
* [.difference(otherHandPose)](#module_instruments/StringedFingering.HandPose+difference) ⇒ Array.<object>
* [.costOfMovement(otherHandPose)](#module_instruments/StringedFingering.HandPose+costOfMovement) ⇒ number
#### new exports.HandPose(fingerPositions)
| Param | Type | Description |
| --- | --- | --- |
| fingerPositions | Array.<number> | Indices 0-9: left thumb, 4 left fingers right thumb, 4 right fingers. Values: null for finger not pressed, {string:number, fret:number} for pressed fingers |
#### handPose.moveFingerTo(index, newPosition)
Move a single finger
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
| Param | Type | Description |
| --- | --- | --- |
| index | number | finger index in [0, 9] |
| newPosition | FretboardPosition | new position |
#### handPose.liftFinger(index)
Lift a single finger
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
| Param | Type | Description |
| --- | --- | --- |
| index | number | finger index in [0, 9] |
#### handPose.moveFingerBy(index, string, fret)
Moves the finger by string and fret
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
| Param | Type | Description |
| --- | --- | --- |
| index | number | finger index in [0, 9] |
| string | number | string |
| fret | number | fret |
#### handPose.moveHandBy(string, fret)
Move the whole hand, fingers keep relative positions
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
| Param | Type | Description |
| --- | --- | --- |
| string | number | string |
| fret | number | fret |
#### handPose.isValid(maxString, maxFret) ⇒ boolean
Checks whether this position is valid
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
**Returns**: boolean - true iff valid
| Param | Type | Description |
| --- | --- | --- |
| maxString | number | max string |
| maxFret | number | max fret |
#### handPose.euqals(otherHandPose) ⇒ boolean
Returns true iff this and another FretboardPosition are equal
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
**Returns**: boolean - ture iff equal
| Param | Type | Description |
| --- | --- | --- |
| otherHandPose | HandPose | another hand pose |
#### handPose.toString() ⇒ string
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
**Returns**: string - string representation
#### handPose.clone() ⇒ HandPose
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
**Returns**: HandPose - clone
#### handPose.difference(otherHandPose) ⇒ Array.<object>
Returns (other - this), i.e. how you need to move this to get to other
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
**Returns**: Array.<object> - difference
| Param | Type | Description |
| --- | --- | --- |
| otherHandPose | HandPose | another HandPose |
#### handPose.costOfMovement(otherHandPose) ⇒ number
Calculates movement costs
**Kind**: instance method of [HandPose](#module_instruments/StringedFingering.HandPose)
**Returns**: number - cost
| Param | Type | Description |
| --- | --- | --- |
| otherHandPose | HandPose | another HandPose |
## fileFormats/Midi
Lookup for many MIDI specifications.
**See**: https://soundprogramming.net/file-formats/
* [fileFormats/Midi](#module_fileFormats/Midi)
* _static_
* [.flatToSharp](#module_fileFormats/Midi.flatToSharp) : Map.<string, string>
* [.sharpToFlat](#module_fileFormats/Midi.sharpToFlat) : Map.<string, string>
* [.NOTE_NAMES](#module_fileFormats/Midi.NOTE_NAMES) : Array.<string>
* [.NOTE_NAMES_FLAT](#module_fileFormats/Midi.NOTE_NAMES_FLAT) : Array.<string>
* [.MIDI_NOTES](#module_fileFormats/Midi.MIDI_NOTES) : Array.<MidiNote>
* [.SHARPS](#module_fileFormats/Midi.SHARPS) : Set.<number>
* [.MIDI_COMMANDS](#module_fileFormats/Midi.MIDI_COMMANDS) : Map.<number, MidiCommand>
* [.MIDI_NOTE_RANGES](#module_fileFormats/Midi.MIDI_NOTE_RANGES) : Array.<object>
* [.getMidiNoteByNr(nr)](#module_fileFormats/Midi.getMidiNoteByNr) ⇒ MidiNote
* [.getMidiNoteByLabel(label)](#module_fileFormats/Midi.getMidiNoteByLabel) ⇒ MidiNote
* [.getMidiNoteByNameAndOctave(name, octave)](#module_fileFormats/Midi.getMidiNoteByNameAndOctave) ⇒ MidiNote
* [.getMidiInstrumentByNr(nr)](#module_fileFormats/Midi.getMidiInstrumentByNr) ⇒ object
* [.getMidiInstrumentByNrL2(nr, subNr)](#module_fileFormats/Midi.getMidiInstrumentByNrL2) ⇒ object
* [.getMidiDrumNoteByNr(nr)](#module_fileFormats/Midi.getMidiDrumNoteByNr) ⇒ string
* [.isSharp(nr)](#module_fileFormats/Midi.isSharp) ⇒ boolean
* [.getNoteNameFromNoteNr(nr)](#module_fileFormats/Midi.getNoteNameFromNoteNr) ⇒ string
* _inner_
* [~GENERAL_MIDI_DRUM_NOTE_NUMBERS](#module_fileFormats/Midi..GENERAL_MIDI_DRUM_NOTE_NUMBERS) : Map.<number, string>
* [~MidiNote](#module_fileFormats/Midi..MidiNote) : object
* [~MidiCommand](#module_fileFormats/Midi..MidiCommand) : object
### fileFormats/Midi.flatToSharp : Map.<string, string>
Maps flats to sharps, e.g. flatToSharp.get('Db') === 'C#'
**Kind**: static constant of [fileFormats/Midi](#module_fileFormats/Midi)
### fileFormats/Midi.sharpToFlat : Map.<string, string>
Maps shaprs to flats, e.g. sharpToFlat.get('C#') === 'Db'
**Kind**: static constant of [fileFormats/Midi](#module_fileFormats/Midi)
### fileFormats/Midi.NOTE\_NAMES : Array.<string>
Names of notes, indexed like MIDI numbers, i.e. C is 0
**Kind**: static constant of [fileFormats/Midi](#module_fileFormats/Midi)
### fileFormats/Midi.NOTE\_NAMES\_FLAT : Array.<string>
Names of notes, indexed like MIDI numbers, i.e. C is 0, with flats instead of
sharps.
**Kind**: static constant of [fileFormats/Midi](#module_fileFormats/Midi)
### fileFormats/Midi.MIDI\_NOTES : Array.<MidiNote>
Index equals MIDI note number
**Kind**: static constant of [fileFormats/Midi](#module_fileFormats/Midi)
### fileFormats/Midi.SHARPS : Set.<number>
Set of all MIDI notes that are sharp/flat
**Kind**: static constant of [fileFormats/Midi](#module_fileFormats/Midi)
**Example** *(Find out if a note is sharp/flat)*
```js
const midiNr = 42;
const isSharp = Midi.SHARPS.has(midiNr);
// true
```
### fileFormats/Midi.MIDI\_COMMANDS : Map.<number, MidiCommand>
MIDI commands with code, name, and parameters
From: https://ccrma.stanford.edu/~craig/articles/linuxmidi/misc/essenmidi.html
https://www.midi.org/specifications/item/table-1-summary-of-midi-message
**Kind**: static constant of [fileFormats/Midi](#module_fileFormats/Midi)
### fileFormats/Midi.MIDI\_NOTE\_RANGES : Array.<object>
**Kind**: static constant of [fileFormats/Midi](#module_fileFormats/Midi)
**Todo**
- [ ] add instrument numbers
- [ ] This might be useful, e.g. to check which notes Player can play
### fileFormats/Midi.getMidiNoteByNr(nr) ⇒ MidiNote
Returns information on the MIDI note with the specified number.
**Kind**: static method of [fileFormats/Midi](#module_fileFormats/Midi)
**Returns**: MidiNote - MIDI note information as a [MidiNote](MidiNote)
| Param | Type | Description |
| --- | --- | --- |
| nr | number | MIDI note number in [0, 127] |
### fileFormats/Midi.getMidiNoteByLabel(label) ⇒ MidiNote
Returns information on the MIDI note with the specified label.
**Kind**: static method of [fileFormats/Midi](#module_fileFormats/Midi)
**Returns**: MidiNote - MIDI note information as a [MidiNote](MidiNote)
| Param | Type | Description |
| --- | --- | --- |
| label | string | note label, e.g. 'D#0' (upper-case and sharp notation necessary) |
### fileFormats/Midi.getMidiNoteByNameAndOctave(name, octave) ⇒ MidiNote
Returns information on the MIDI note with the specified name and octave.
**Kind**: static method of [fileFormats/Midi](#module_fileFormats/Midi)
**Returns**: MidiNote - MIDI note information as a [MidiNote](MidiNote)
| Param | Type | Description |
| --- | --- | --- |
| name | string | note name, e.g. 'D#' (upper-case and sharp notation necessary) |
| octave | number | octave in [-1, 9] |
### fileFormats/Midi.getMidiInstrumentByNr(nr) ⇒ object
Returns information on the MIDI instrument with the specified number.
**Kind**: static method of [fileFormats/Midi](#module_fileFormats/Midi)
**Returns**: object - note info, e.g.
{ number: 0, group: 'Piano', label: 'Acoustic Grand Piano' }
| Param | Type | Description |
| --- | --- | --- |
| nr | number | MIDI instrument number in [0, 127] |
### fileFormats/Midi.getMidiInstrumentByNrL2(nr, subNr) ⇒ object
Returns information on the MIDI instrument (MIDI level 2) with the
specified number.
**Kind**: static method of [fileFormats/Midi](#module_fileFormats/Midi)
**Returns**: object - note info, e.g.
{ number: 0, group: 'Piano', label: 'Acoustic Grand Piano' }
| Param | Type | Description |
| --- | --- | --- |
| nr | number | MIDI instrument number in [0, 127] |
| subNr | number | MIDI instrument sub number in [0, 127] |
### fileFormats/Midi.getMidiDrumNoteByNr(nr) ⇒ string
Returns information on the MIDI instrument with the specified number.
**Kind**: static method of [fileFormats/Midi](#module_fileFormats/Midi)
**Returns**: string - note name, e.g. 'Bass Drum 1
| Param | Type | Description |
| --- | --- | --- |
| nr | number | MIDI drum note number in [27, 87] |
### fileFormats/Midi.isSharp(nr) ⇒ boolean
Returns true if a given MIDI pitch refers to a sharp note.
**Kind**: static method of [fileFormats/Midi](#module_fileFormats/Midi)
**Returns**: boolean - true if sharp, false otherwise
| Param | Type | Description |
| --- | --- | --- |
| nr | number | MIDI note number in [0, 127] |
### fileFormats/Midi.getNoteNameFromNoteNr(nr) ⇒ string
Returns a note name such as 'C#' (without octave) for a given MIDI
note number.
**Kind**: static method of [fileFormats/Midi](#module_fileFormats/Midi)
**Returns**: string - note name such as 'C#'
| Param | Type | Description |
| --- | --- | --- |
| nr | number | MIDI note number in [0, 127] |
### fileFormats/Midi~GENERAL\_MIDI\_DRUM\_NOTE\_NUMBERS : Map.<number, string>
**Kind**: inner constant of [fileFormats/Midi](#module_fileFormats/Midi)
### fileFormats/Midi~MidiNote : object
A MIDI note
**Kind**: inner typedef of [fileFormats/Midi](#module_fileFormats/Midi)
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| pitch | number | the MIDI note number e.g. 60 for C4 |
| name | string | e.g. C# |
| octave | number | number in [-1, 9] |
| label | string | name and octave, e.g. C#5 |
| frequency | number | physical frequency |
**Example** *(Example for a MIDI note)*
```js
{ pitch: 69, name: 'A', octave: 4, label: 'A4', frequency: 440.000 }
```
### fileFormats/Midi~MidiCommand : object
A MIDI command
**Kind**: inner typedef of [fileFormats/Midi](#module_fileFormats/Midi)
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| name | string | e.g. 'noteOn' |
| description | string | e.g. 'Note-on' |
| params | Array.<string> \| undefined | additional prameters of that command |
**Example** *(Example for a MIDI command)*
```js
{ name: 'noteOn', description: 'Note-on', params: ['key', 'velocity'] }],
```
## fileFormats/MidiParser
**Todo**
- [ ] parse pitch bends
- [ ] after tempo changes notes and measure time do not align,
see "[Test] Tempo change.mid"
* [fileFormats/MidiParser](#module_fileFormats/MidiParser)
* _static_
* [.preprocessMidiFileData(data, splitFormat0IntoTracks, log)](#module_fileFormats/MidiParser.preprocessMidiFileData) ⇒ object
* _inner_
* [~EVENT_TYPES](#module_fileFormats/MidiParser..EVENT_TYPES) : object
* [~META_TYPES](#module_fileFormats/MidiParser..META_TYPES) : object
* [~KEY_SIG_MAP](#module_fileFormats/MidiParser..KEY_SIG_MAP) : Map.<number, object>
* [~getMeasureIndices(notes, measureTimes)](#module_fileFormats/MidiParser..getMeasureIndices) ⇒ Array.<number>
### fileFormats/MidiParser.preprocessMidiFileData(data, splitFormat0IntoTracks, log) ⇒ object
Parses a MIDI JSON file to get Note objects with absolute time in seconds.
**Kind**: static method of [fileFormats/MidiParser](#module_fileFormats/MidiParser)
**Returns**: object - including an array of note objects and meta information
**See**: https://github.com/colxi/midi-parser-js/wiki/MIDI-File-Format-Specifications
| Param | Type | Description |
| --- | --- | --- |
| data | object | MIDI data in JSON format |
| splitFormat0IntoTracks | boolean | split MIDI format 0 data into tracks instead of using channels? |
| log | boolean | set to true to log results etc. to the console |
### fileFormats/MidiParser~EVENT\_TYPES : object
MIDI event types and meta types and their codes
**Kind**: inner constant of [fileFormats/MidiParser](#module_fileFormats/MidiParser)
**See**: https://github.com/colxi/midi-parser-js/wiki/MIDI-File-Format-Specifications
Event Type Value Value decimal Parameter 1 Parameter 2
Note Off 0x8 8 note number velocity
Note On 0x9 9 note number velocity
Note Aftertouch 0xA 10 note number aftertouch value
Controller 0xB 11 controller number controller value
Program Change 0xC 12 program number not used
Channel Aftertouch 0xD 13 aftertouch value not used
Pitch Bend 0xE 14 pitch value (LSB) pitch value (MSB)
Meta 0xFF 255 parameters depend on meta type
### fileFormats/MidiParser~META\_TYPES : object
**Kind**: inner constant of [fileFormats/MidiParser](#module_fileFormats/MidiParser)
### fileFormats/MidiParser~KEY\_SIG\_MAP : Map.<number, object>
Maps needed for key signature detection from number of sharps / flats
**Kind**: inner constant of [fileFormats/MidiParser](#module_fileFormats/MidiParser)
**See**: https://www.recordingblogs.com/wiki/midi-key-signature-meta-message
### fileFormats/MidiParser~getMeasureIndices(notes, measureTimes) ⇒ Array.<number>
For the notes of one track, computes the notes' indices where new measures
start.
**Kind**: inner method of [fileFormats/MidiParser](#module_fileFormats/MidiParser)
**Returns**: Array.<number> - measure indices
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes of a track |
| measureTimes | Array.<numer> | times in seconds where new measures start |
## fileFormats/MusicXmlParser
* [fileFormats/MusicXmlParser](#module_fileFormats/MusicXmlParser)
* _static_
* [.preprocessMusicXmlData(xml, log)](#module_fileFormats/MusicXmlParser.preprocessMusicXmlData) ⇒ object
* _inner_
* [~keySignatureMap](#module_fileFormats/MusicXmlParser..keySignatureMap) : Map.<number, object>
* [~dynamicsMap](#module_fileFormats/MusicXmlParser..dynamicsMap) : Map.<string, number>
* [~removeRehearsalRepetitions(measureRehearsalMap)](#module_fileFormats/MusicXmlParser..removeRehearsalRepetitions) ⇒ Map.<number, string>
* [~getLyricsFromNote(note)](#module_fileFormats/MusicXmlParser..getLyricsFromNote) ⇒ string
* [~getDrumInstrumentMap(xml)](#module_fileFormats/MusicXmlParser..getDrumInstrumentMap) ⇒ Map
### fileFormats/MusicXmlParser.preprocessMusicXmlData(xml, log) ⇒ object
Converts a collection of MusicXML measures to JavaScript Objects with timing information in seconds.
Also calculates the position of measure lines and the total time in seconds.
**Kind**: static method of [fileFormats/MusicXmlParser](#module_fileFormats/MusicXmlParser)
**Returns**: object - parsed document
| Param | Type | Description |
| --- | --- | --- |
| xml | XMLDocument | MusicXML document |
| log | boolean | set to true to log results etc. to the console |
### fileFormats/MusicXmlParser~keySignatureMap : Map.<number, object>
Map from fiths to key signature
**Kind**: inner constant of [fileFormats/MusicXmlParser](#module_fileFormats/MusicXmlParser)
### fileFormats/MusicXmlParser~dynamicsMap : Map.<string, number>
Maps dynamics to MIDI velocity numbers, i.e. 'ff' to 102
**Kind**: inner constant of [fileFormats/MusicXmlParser](#module_fileFormats/MusicXmlParser)
### fileFormats/MusicXmlParser~removeRehearsalRepetitions(measureRehearsalMap) ⇒ Map.<number, string>
Removes duplicates from measureRehearsalMap, which occur when a measure was
repeated
**Kind**: inner method of [fileFormats/MusicXmlParser](#module_fileFormats/MusicXmlParser)
**Returns**: Map.<number, string> - cleaned map
| Param | Type | Description |
| --- | --- | --- |
| measureRehearsalMap | Map.<number, string> | map |
### fileFormats/MusicXmlParser~getLyricsFromNote(note) ⇒ string
Reads lyrics from a note element
**Kind**: inner method of [fileFormats/MusicXmlParser](#module_fileFormats/MusicXmlParser)
**Returns**: string - lyrics for this note
| Param | Type | Description |
| --- | --- | --- |
| note | HTMLElement | note element |
### fileFormats/MusicXmlParser~getDrumInstrumentMap(xml) ⇒ Map
Returns a map containing maps, such that result.get(partId).get(instrId)
gives you the instrument with the ID instrId as defined in the part partId.
This is needed to map drum notes to MIDI pitches.
**Kind**: inner method of [fileFormats/MusicXmlParser](#module_fileFormats/MusicXmlParser)
**Returns**: Map - map with structure result.get(partId).get(instrId)
| Param | Type | Description |
| --- | --- | --- |
| xml | XMLDocument | MusicXML |
## graphics/Canvas
**Todo**
- [ ] combine multiple canvases into one, by drawing over common background
- [ ] save canvas as file https://www.digitalocean.com/community/tutorials/js-canvas-toblob
* [graphics/Canvas](#module_graphics/Canvas)
* [.setupCanvas(canvas)](#module_graphics/Canvas.setupCanvas) ⇒ CanvasRenderingContext2D
* [.drawLine(context, x1, y1, x2, y2)](#module_graphics/Canvas.drawLine) ⇒ void
* ~~[.drawHLine(context, x1, y, x2)](#module_graphics/Canvas.drawHLine) ⇒ void~~
* ~~[.drawVLine(context, x, y1, y2)](#module_graphics/Canvas.drawVLine) ⇒ void~~
* [.drawBowRight(context, x1, y1, x2, y2, [strength])](#module_graphics/Canvas.drawBowRight)
* [.drawCircle(context, x, y, radius)](#module_graphics/Canvas.drawCircle) ⇒ void
* [.drawFilledCircle(context, x, y, radius)](#module_graphics/Canvas.drawFilledCircle) ⇒ void
* [.drawTriangle(context, x, y, halfSize)](#module_graphics/Canvas.drawTriangle) ⇒ void
* [.drawDiamond(context, x, y, halfSize)](#module_graphics/Canvas.drawDiamond) ⇒ void
* [.drawX(context, x, y, halfSize)](#module_graphics/Canvas.drawX) ⇒ void
* [.drawNoteTrapezoid(context, x, y, width, height, height2)](#module_graphics/Canvas.drawNoteTrapezoid) ⇒ void
* [.drawNoteTrapezoidUpwards(context, x, y, width, height, width2)](#module_graphics/Canvas.drawNoteTrapezoidUpwards) ⇒ void
* [.drawRoundedRect(context, x, y, width, height, radius)](#module_graphics/Canvas.drawRoundedRect) ⇒ void
* [.drawCornerLine(context, x1, y1, x2, y2, [xFirst])](#module_graphics/Canvas.drawCornerLine)
* [.drawRoundedCornerLine(context, x1, y1, x2, y2, [maxRadius])](#module_graphics/Canvas.drawRoundedCornerLine)
* [.drawRoundedCornerLineRightLeft(context, x1, y1, x2, y2, [maxRadius])](#module_graphics/Canvas.drawRoundedCornerLineRightLeft)
* [.drawHexagon(context, cx, cy, radius)](#module_graphics/Canvas.drawHexagon)
* [.drawBezierConnectorX(context, x1, y1, x2, y2)](#module_graphics/Canvas.drawBezierConnectorX)
* [.drawBezierConnectorY(context, x1, y1, x2, y2)](#module_graphics/Canvas.drawBezierConnectorY)
* [.drawBezierFunnelY(context, y1, y2, x1left, x1right, x2left, x2right)](#module_graphics/Canvas.drawBezierFunnelY)
* [.drawRoundedCorner(context, x1, y1, x2, y2, turnLeft, roundness)](#module_graphics/Canvas.drawRoundedCorner)
* [.drawArc(context, startX1, startX2, length, yBottom)](#module_graphics/Canvas.drawArc)
* [.drawAssymetricArc(context, startX1, endX1, startX2, endX2, yBottom)](#module_graphics/Canvas.drawAssymetricArc)
* [.drawBracketH(context, x, y, w, h)](#module_graphics/Canvas.drawBracketH)
* [.drawMatrix(context, matrix, [x], [y], [size], colorMap)](#module_graphics/Canvas.drawMatrix)
* [.drawColorRamp(context, colorMap)](#module_graphics/Canvas.drawColorRamp)
* [.drawNoteColorMap(context, colors, w, h, [x], [y], [fontSize])](#module_graphics/Canvas.drawNoteColorMap)
* [.drawVerticalText(context, x, y, text, [color], [font], [centered])](#module_graphics/Canvas.drawVerticalText)
### graphics/Canvas.setupCanvas(canvas) ⇒ CanvasRenderingContext2D
Sets up a canvas rescaled to device pixel ratio
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
**Returns**: CanvasRenderingContext2D - canvas rendering context
| Param | Type | Description |
| --- | --- | --- |
| canvas | HTMLCanvasElement | canvas element |
### graphics/Canvas.drawLine(context, x1, y1, x2, y2) ⇒ void
Draws a stroked straight line.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x1 | number | x coordinate of the start |
| y1 | number | y coordinate of the start |
| x2 | number | x coordinate of end |
| y2 | number | y coordinate of end |
**Example**
```js
// Set the strokeStyle first
context.strokeStyle = 'black';
// Let's draw an X
Canvas.drawLine(context, 0, 0, 50, 50);
Canvas.drawLine(context, 0, 50, 50, 0);
```
### ~~graphics/Canvas.drawHLine(context, x1, y, x2) ⇒ void~~
***Deprecated***
Draws a stroked straight horizontal line.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x1 | number | x coordinate of the start |
| y | number | y coordinate of the start |
| x2 | number | x coordinate of end |
### ~~graphics/Canvas.drawVLine(context, x, y1, y2) ⇒ void~~
***Deprecated***
Draws a stroked straight vertical line.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of the start |
| y1 | number | y coordinate of the start |
| y2 | number | y coordinate of end |
### graphics/Canvas.drawBowRight(context, x1, y1, x2, y2, [strength])
Draws a line that bows to the right in the direction of travel (looks like a
left turn), thereby encoding direction. Useful for node-link graphs.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| context | CanvasRenderingContext2D | | canvas rendering context |
| x1 | number | | x coordinate of the start |
| y1 | number | | y coordinate of the start |
| x2 | number | | x coordinate of end |
| y2 | number | | y coordinate of end |
| [strength] | number | 0.5 | how much the bow deviates from a straight line towards the right, negative values will make bows to the left |
### graphics/Canvas.drawCircle(context, x, y, radius) ⇒ void
Draws a stroked circle.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of center |
| y | number | y coordinate of center |
| radius | number | radius |
### graphics/Canvas.drawFilledCircle(context, x, y, radius) ⇒ void
Draws a filled circle.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of center |
| y | number | y coordinate of center |
| radius | number | radius |
### graphics/Canvas.drawTriangle(context, x, y, halfSize) ⇒ void
Draws a filled triangle like this: /\
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of center |
| y | number | y coordinate of center |
| halfSize | number | half of the size |
### graphics/Canvas.drawDiamond(context, x, y, halfSize) ⇒ void
Draws a diamond like this: <>
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of center |
| y | number | y coordinate of center |
| halfSize | number | half of the size |
### graphics/Canvas.drawX(context, x, y, halfSize) ⇒ void
Draws an X
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of center |
| y | number | y coordinate of center |
| halfSize | number | half of the size |
### graphics/Canvas.drawNoteTrapezoid(context, x, y, width, height, height2) ⇒ void
Draws a trapezoid that looks like a rectangle but gets narrower at the right
end, so better show where one ends and the next begins.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of top left |
| y | number | y coordinate of top left |
| width | number | width |
| height | number | height (of left side) |
| height2 | number | height (of right side) |
### graphics/Canvas.drawNoteTrapezoidUpwards(context, x, y, width, height, width2) ⇒ void
Draws a trapezoid that looks like a rectangle but gets narrower at the top
end, so better show where one ends and the next begins.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of bounding rect's top left |
| y | number | y coordinate of bounding rect's top left |
| width | number | width (of bounding rect / bottom side) |
| height | number | height |
| width2 | number | width (of top side) |
### graphics/Canvas.drawRoundedRect(context, x, y, width, height, radius) ⇒ void
Draws a rectangle with rounded corners, does not fill or stroke by itself
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x coordinate of bounding rect's top left |
| y | number | y coordinate of bounding rect's top left |
| width | number | width |
| height | number | height |
| radius | number | rounding radius |
### graphics/Canvas.drawCornerLine(context, x1, y1, x2, y2, [xFirst])
Draws a horizontal, then vertical line to connect two points (or the other
way round when xFirst == false)
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| context | CanvasRenderingContext2D | | canvas rendering context |
| x1 | number | | x coordinate of start |
| y1 | number | | y coordinate of start |
| x2 | number | | x coordinate of end |
| y2 | number | | y coordinate of end |
| [xFirst] | boolean | true | controls whether to go first in x or y direction |
### graphics/Canvas.drawRoundedCornerLine(context, x1, y1, x2, y2, [maxRadius])
Draws a rounded version of drawCornerLine().
Only works for dendrograms drawn from top-dowm, use
drawRoundedCornerLineRightLeft for right-to-left dendrograms.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| context | CanvasRenderingContext2D | | canvas rendering context |
| x1 | number | | x coordinate of start |
| y1 | number | | y coordinate of start |
| x2 | number | | x coordinate of end |
| y2 | number | | y coordinate of end |
| [maxRadius] | number | 25 | maximum radius, fixes possible overlaps |
### graphics/Canvas.drawRoundedCornerLineRightLeft(context, x1, y1, x2, y2, [maxRadius])
Draws a rounded version of drawRoundedCornerLine for right-to-left
dendrograms.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| context | CanvasRenderingContext2D | | canvas rendering context |
| x1 | number | | x coordinate of start |
| y1 | number | | y coordinate of start |
| x2 | number | | x coordinate of end |
| y2 | number | | y coordinate of end |
| [maxRadius] | number | 25 | maximum radius, fixes possible overlaps |
### graphics/Canvas.drawHexagon(context, cx, cy, radius)
Draws a hexagon, call context.fill() or context.stroke() afterwards.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| cx | number | center x |
| cy | number | center y |
| radius | number | radius of the circle on which the points are placed |
### graphics/Canvas.drawBezierConnectorX(context, x1, y1, x2, y2)
Draws a Bezier curve to connect to points in X direction.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x1 | number | x coordinate of the first point |
| y1 | number | y coordinate of the first point |
| x2 | number | x coordinate of the second point |
| y2 | number | y coordinate of the second point |
### graphics/Canvas.drawBezierConnectorY(context, x1, y1, x2, y2)
Draws a Bezier curve to connect to points in Y direction.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x1 | number | x coordinate of the first point |
| y1 | number | y coordinate of the first point |
| x2 | number | x coordinate of the second point |
| y2 | number | y coordinate of the second point |
### graphics/Canvas.drawBezierFunnelY(context, y1, y2, x1left, x1right, x2left, x2right)
Draws a funnel to indicate that horizontal span relates to another one below
Will fill() the shape, call context.stroke() afterwards to also stroke.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
**Todo**
- [ ] add X version
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| y1 | number | top y position |
| y2 | number | bottom y position |
| x1left | number | top left x position |
| x1right | number | top right x position |
| x2left | number | bottom left x position |
| x2right | number | bottom right x position |
### graphics/Canvas.drawRoundedCorner(context, x1, y1, x2, y2, turnLeft, roundness)
Draws a rounded corner, requires x and y distances between points to be
equal.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x1 | number | x coordinate of the first point |
| y1 | number | y coordinate of the first point |
| x2 | number | x coordinate of the second point |
| y2 | number | y coordinate of the second point |
| turnLeft | boolean | true for left turn, false for right turn |
| roundness | number | corner roundness between 0 (sharp) and 1 (round) |
### graphics/Canvas.drawArc(context, startX1, startX2, length, yBottom)
Draws an arc that connects similar parts.
Both parts must have the same width in pixels.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| startX1 | number | x coordinate of the start of the first part |
| startX2 | number | x coordinate of the start of the second part |
| length | number | length in pixels of the parts |
| yBottom | number | bottom baseline y coordinate |
### graphics/Canvas.drawAssymetricArc(context, startX1, endX1, startX2, endX2, yBottom)
Draws a more complex path and fills it.
Two arcs: One from startX1 to endX2 on the top, one from endX1 to startX2
below it.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| startX1 | number | x coordinate of the start of the first part |
| endX1 | number | x coordinate of the end of the first part |
| startX2 | number | x coordinate of the start of the second part |
| endX2 | number | x coordinate of the end of the second part |
| yBottom | number | bottom baseline y coordinate |
### graphics/Canvas.drawBracketH(context, x, y, w, h)
Draws a horizontal bracket like this |_____| (bottom)
or this |""""""| (top).
Use a positive h for bottom and a negative one for top.
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| x | number | x position of the bracket's horizontal lines |
| y | number | y position of the bracket's horizontal lines |
| w | number | width of the bracket's horizontal lines |
| h | number | height of the bracket's vertical ticks |
### graphics/Canvas.drawMatrix(context, matrix, [x], [y], [size], colorMap)
Draws a quadratic matrix onto a canvas
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| context | CanvasRenderingContext2D | | canvas rendering context |
| matrix | Array.<Array.<number>> | | matrix |
| [x] | number | 0 | x position of the top left corner |
| [y] | number | 0 | y position of the top left corner |
| [size] | number | 400 | width and height in pixel |
| colorMap | function | | colormap from [min, max] to a color |
### graphics/Canvas.drawColorRamp(context, colorMap)
Draws a color ramp
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
| Param | Type | Description |
| --- | --- | --- |
| context | CanvasRenderingContext2D | canvas rendering context |
| colorMap | function | colormap from [min, max] to a color |
### graphics/Canvas.drawNoteColorMap(context, colors, w, h, [x], [y], [fontSize])
Draws a color map as small rectanlges below the notes C, C#, ...
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
**Todo**
- [ ] test
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| context | CanvasRenderingContext2D | | canvas rendering context |
| colors | Array.<string> | | colors, e.g., from NoteColorUtils |
| w | number | | |
| h | number | | |
| [x] | number | 0 | |
| [y] | number | 0 | |
| [fontSize] | number | 12 | |
### graphics/Canvas.drawVerticalText(context, x, y, text, [color], [font], [centered])
Draws text horizontally rotated 90 degrees clock-wise
**Kind**: static method of [graphics/Canvas](#module_graphics/Canvas)
**Todo**
- [ ] use the one from mvlib
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| context | \* | | |
| x | number | | x position |
| y | number | | y position |
| text | string | | text |
| [color] | string | "'black'" | HTML color string |
| [font] | string | "'12px sans-serif'" | font string, e.g, '12px sans-serif' |
| [centered] | boolean | false | center text? |
## Svg
**Todo**
- [ ] test
- [ ] export
* [Svg](#module_Svg)
* [.getSvgArrowTipPath(toX, toY, pointTo, tipSize)](#module_Svg.getSvgArrowTipPath) ⇒ string
* [.getSvgCArrowPath(fromX, fromY, toX, toY, pointTo, tipSize)](#module_Svg.getSvgCArrowPath) ⇒ string
* [.getSvgCArrowPath2(fromX, fromY, toX, toY, width, pointTo, tipSize)](#module_Svg.getSvgCArrowPath2) ⇒ string
* [.getSvgHorizontalSArrowPath(fromX, fromY, toX, toY, tipSize, pointTo)](#module_Svg.getSvgHorizontalSArrowPath) ⇒ string
* [.getSvgVerticalSArrowPath(fromX, fromY, toX, toY, tipSize, pointTo)](#module_Svg.getSvgVerticalSArrowPath) ⇒ string
### Svg.getSvgArrowTipPath(toX, toY, pointTo, tipSize) ⇒ string
Draws an arrow tip with two straight lines.
**Kind**: static method of [Svg](#module_Svg)
**Returns**: string - arrow tip SVG path 'd' attribute
| Param | Type | Description |
| --- | --- | --- |
| toX | number | x coordinate where the arrow is pointing |
| toY | number | y coordinate where the arrow is pointing |
| pointTo | string | top, right, bottom, left, top-right, top-left, bottom-right, bottom-left |
| tipSize | number | size of the arrow tip |
### Svg.getSvgCArrowPath(fromX, fromY, toX, toY, pointTo, tipSize) ⇒ string
Creates a roughly C-shaped arrow (quarter ellipse).
**Kind**: static method of [Svg](#module_Svg)
**Returns**: string - SVG path 'd' attribute
| Param | Type | Description |
| --- | --- | --- |
| fromX | number | starting x |
| fromY | number | starting y |
| toX | number | target x |
| toY | number | target y |
| pointTo | string | top, right, bottom, left, top-right, top-left, bottom-right, bottom-left |
| tipSize | number | size of the tip |
### Svg.getSvgCArrowPath2(fromX, fromY, toX, toY, width, pointTo, tipSize) ⇒ string
Creates a C-shaped arrow (half elipse).
**Kind**: static method of [Svg](#module_Svg)
**Returns**: string - SVG path 'd' attribute
| Param | Type | Description |
| --- | --- | --- |
| fromX | number | starting x |
| fromY | number | starting y |
| toX | number | target x |
| toY | number | target y |
| width | number | width |
| pointTo | string | top, right, bottom, left, top-right, top-left, bottom-right, bottom-left |
| tipSize | number | size of the tip |
### Svg.getSvgHorizontalSArrowPath(fromX, fromY, toX, toY, tipSize, pointTo) ⇒ string
Creates a roughly S-shaped arrow (horizontal).
**Kind**: static method of [Svg](#module_Svg)
**Returns**: string - SVG path 'd' attribute
| Param | Type | Description |
| --- | --- | --- |
| fromX | number | starting x |
| fromY | number | starting y |
| toX | number | target x |
| toY | number | target y |
| tipSize | number | size of the tip |
| pointTo | string | top, right, bottom, left, top-right, top-left, bottom-right, bottom-left |
### Svg.getSvgVerticalSArrowPath(fromX, fromY, toX, toY, tipSize, pointTo) ⇒ string
Creates a roughly S-shaped arrow (vertical).
**Kind**: static method of [Svg](#module_Svg)
**Returns**: string - SVG path 'd' attribute
| Param | Type | Description |
| --- | --- | --- |
| fromX | number | starting x |
| fromY | number | starting y |
| toX | number | target x |
| toY | number | target y |
| tipSize | number | size of the tip |
| pointTo | string | top, right, bottom, left, top-right, top-left, bottom-right, bottom-left |
## musicvis-lib
### musicvis-lib.getVersion() ⇒ string
Returns the current version of the library
**Kind**: static method of [musicvis-lib](#module_musicvis-lib)
**Returns**: string - version string
## input/AudioRecorder ⇒ Promise
Allows to record audio blobs.
**Returns**: Promise - audio recorder
**See**
- https://medium.com/@bryanjenningz/how-to-record-and-play-audio-in-javascript-faa1b2b3e49b
- https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder
**Example** *(Usage (only in async functions))*
```js
const recorder = await recordAudio();
recorder.start();
// ...
const audio = await recorder.stop();
stop() returns a Blob with audio data
```
## input/MidiInputManager
Handles incoming MIDI messages from a MIDI device.
* [input/MidiInputManager](#module_input/MidiInputManager)
* [~MidiInputManager](#module_input/MidiInputManager..MidiInputManager)
* [new MidiInputManager(getMidiLiveData, setMidiLiveData, addCurrentNote, removeCurrentNote)](#new_module_input/MidiInputManager..MidiInputManager_new)
### input/MidiInputManager~MidiInputManager
**Kind**: inner class of [input/MidiInputManager](#module_input/MidiInputManager)
#### new MidiInputManager(getMidiLiveData, setMidiLiveData, addCurrentNote, removeCurrentNote)
Constructor with callback functions
| Param | Type | Description |
| --- | --- | --- |
| getMidiLiveData | function | a function called by this object to get the currently recorded MIDI notes from App.js, where the MidiInputManager instance should be created Example for how to defined getMidiLiveData as method in App.js: getMidiLiveData = () => this.state.midiLiveData; |
| setMidiLiveData | function | a function called by this object to update the currently MIDI notes in App.js Example: setMidiLiveData = (data) => { // Work-around so note_off event handling can // immediately find the note_on event this.state.midiLiveData = data; this.setState({ midiLiveData: data }); }; |
| addCurrentNote | function | a function called by this object to add a currently played note (e.g. currently pressed piano key) Example: addCurrentNote = (note) => { const newMap = new Map(this.state.currentNotes).set(note.pitch, note); this.setState({ currentNotes: newMap }); } |
| removeCurrentNote | function | a function called by this object to remove a currently played note Example: removeCurrentNote = (pitch) => { const newMap = new Map(this.state.currentNotes).delete(pitch); this.setState({ currentNotes: newMap }); } |
## input/MidiRecorder ⇒ Promise
Records incoming MIDI messages from a MIDI device.
**Returns**: Promise - MIDI recorder
| Param | Type | Description |
| --- | --- | --- |
| [onMessage] | function | a callback function to get notfied of incoming messages |
**Example** *(Usage (only in async functions))*
```js
const recorder = await recordMidi();
recorder.start();
const notes = recorder.stop();
```
## instruments/Drums
* [instruments/Drums](#module_instruments/Drums)
* [.DRUM_PARTS](#module_instruments/Drums.DRUM_PARTS) : object
* [.DRUM_ACTIONS](#module_instruments/Drums.DRUM_ACTIONS) : object
* [.DRUM_PARTS_ACTIONS](#module_instruments/Drums.DRUM_PARTS_ACTIONS) : object
* [.drumPitchReplacementMapMPS850](#module_instruments/Drums.drumPitchReplacementMapMPS850) : Map.<number, object>
* [.generateDrumVariation(data, deviation, pAdd, pRemove)](#module_instruments/Drums.generateDrumVariation) ⇒ [Array.<Note>](#Note)
* [.simplifyDrumPitches(notes, replacementMap)](#module_instruments/Drums.simplifyDrumPitches) ⇒ Array.<Notes>
* [.getPitch2PositionMap(replacementMap)](#module_instruments/Drums.getPitch2PositionMap) ⇒ Map
### instruments/Drums.DRUM\_PARTS : object
Drum parts
**Kind**: static constant of [instruments/Drums](#module_instruments/Drums)
### instruments/Drums.DRUM\_ACTIONS : object
Drum actions
**Kind**: static constant of [instruments/Drums](#module_instruments/Drums)
### instruments/Drums.DRUM\_PARTS\_ACTIONS : object
Drum parts and actions
**Kind**: static constant of [instruments/Drums](#module_instruments/Drums)
**Todo**
- [ ] still incomplete
### instruments/Drums.drumPitchReplacementMapMPS850 : Map.<number, object>
Pitches that are mapped onto themselves are included for other information.
Millenium MPS-850 https://www.thomann.de/de/millenium_mps_850_e_drum_set.htm
Notation info (line and shape of symbol) so drum notation can generate a lookup from this
https://en.wikipedia.org/wiki/Percussion_notation#/media/File:Sibelius_drum_legend.png
Lines start with 0 at the top above the top most horizontal notation line,
using incremental integers for every possible position, i.e. for on and between lines
Legend:
Map key: The orignal pitch from the input data
repPitch: Replacement pitch, used to simplify multiple zones into one
zone: Zone of the instrument this pitch comes from
order: visual order ranking of this intrumentin the UI (top-bottom or left-right)
line: y position in the drum notation (using integers for every possible position)
shape: Note shape in notation: triangle, <>, x, o, ostroke, xstroke
label: Short label for this intrument
name: Full name of this instrument
**Kind**: static constant of [instruments/Drums](#module_instruments/Drums)
### instruments/Drums.generateDrumVariation(data, deviation, pAdd, pRemove) ⇒ [Array.<Note>](#Note)
Generates a variation of an array of notes by adding, removing or changing notes
**Kind**: static method of [instruments/Drums](#module_instruments/Drums)
**Returns**: [Array.<Note>](#Note) - variated Note array
| Param | Type | Description |
| --- | --- | --- |
| data | [Array.<Note>](#Note) | array of notes |
| deviation | number | width of the Gauss kernel |
| pAdd | number | probability of adding a note after each note |
| pRemove | number | probability of removing each note |
### instruments/Drums.simplifyDrumPitches(notes, replacementMap) ⇒ Array.<Notes>
Replaces pitches based on replacementMap
**Kind**: static method of [instruments/Drums](#module_instruments/Drums)
**Returns**: Array.<Notes> - notes with replaced pitches
**Throws**:
- 'No replacement map given!' when replacementMap is missing
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| replacementMap | Map | a map pitch->replacementPitch |
### instruments/Drums.getPitch2PositionMap(replacementMap) ⇒ Map
Returns a Map:pitch->yPosIndex for views to lookup which row
a pitch has to be drawn in
**Kind**: static method of [instruments/Drums](#module_instruments/Drums)
**Returns**: Map - Map:pitch->yPosIndex
| Param | Type | Description |
| --- | --- | --- |
| replacementMap | Map | a pitch replacement map |
## instruments/Guitar
* [instruments/Guitar](#module_instruments/Guitar)
* [.StringedTuning](#module_instruments/Guitar.StringedTuning)
* [new exports.StringedTuning(name, notes)](#new_module_instruments/Guitar.StringedTuning_new)
* [.stringedTunings](#module_instruments/Guitar.stringedTunings) : Map.<string, Map.<number, StringedTuning>>
* [.stringColors](#module_instruments/Guitar.stringColors) : Array.<string>
* [.guitarNoteFromNote(note, tuning)](#module_instruments/Guitar.guitarNoteFromNote) ⇒ [GuitarNote](#GuitarNote)
* [.getTuningFromPitches(pitches)](#module_instruments/Guitar.getTuningFromPitches) ⇒ StringedTuning \| null
* [.getTuningPitchRange(tuning, fretCount)](#module_instruments/Guitar.getTuningPitchRange) ⇒ Array.<number>
* [.getPitchFromFretboardPos(string, fret, tuning)](#module_instruments/Guitar.getPitchFromFretboardPos) ⇒ number
* [.getNoteInfoFromFretboardPos(string, fret, tuning)](#module_instruments/Guitar.getNoteInfoFromFretboardPos) ⇒ object
* [.getFretboardPositionsFromPitch(pitch, tuning, fretCount)](#module_instruments/Guitar.getFretboardPositionsFromPitch) ⇒ Array.<object>
* [.getFretboardPositionsFromNoteName(name, tuning, fretCount)](#module_instruments/Guitar.getFretboardPositionsFromNoteName) ⇒ Array.<object>
* [.generateExampleData(startTime, count, tuning)](#module_instruments/Guitar.generateExampleData) ⇒ [Array.<GuitarNote>](#GuitarNote)
* [.fretboardPositionsFromMidi(notes, tuning, fretCount)](#module_instruments/Guitar.fretboardPositionsFromMidi) ⇒ [Array.<GuitarNote>](#GuitarNote)
### instruments/Guitar.StringedTuning
Represents a tuning of a fretted string instrument.
**Kind**: static class of [instruments/Guitar](#module_instruments/Guitar)
#### new exports.StringedTuning(name, notes)
Represents a tuning of a fretted string instrument.
| Param | Type | Description |
| --- | --- | --- |
| name | string | name |
| notes | Array.<string> | array of notes, e.g. ['E2', 'A2', 'D3', ...] |
### instruments/Guitar.stringedTunings : Map.<string, Map.<number, StringedTuning>>
Maps from instrument to string number to list of tunings.
Defaults are at the top.
**Kind**: static constant of [instruments/Guitar](#module_instruments/Guitar)
**Todo**
- [ ] add more? https://en.wikipedia.org/wiki/List_of_guitar_tunings
- [ ] https://github.com/PirtleShell/string-tunings/blob/master/tunings.json
- [ ] replace arrays by maps? tuning name - tuning
**Example**
```js
stringedTunings.get('Guitar').get(6) for 6-string guitar tunings
```
### instruments/Guitar.stringColors : Array.<string>
Colors for guitar strings, acces via stringColor[string]
where string in [1, 8].
**Kind**: static constant of [instruments/Guitar](#module_instruments/Guitar)
### instruments/Guitar.guitarNoteFromNote(note, tuning) ⇒ [GuitarNote](#GuitarNote)
For Notes that have a guitar string encoded in their channel, this function
allows to convert them to a GuitarNote.
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: [GuitarNote](#GuitarNote) - a GuitarNote
| Param | Type | Description |
| --- | --- | --- |
| note | [Note](#Note) | a Note that has the guitar string stored in its channel e.g. 0 to 5 for a six string |
| tuning | StringedTuning | tuning |
### instruments/Guitar.getTuningFromPitches(pitches) ⇒ StringedTuning \| null
Returns a tuning with the specified pitches or null if none found.
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: StringedTuning \| null - the found tuning or null
| Param | Type | Description |
| --- | --- | --- |
| pitches | Array.<number> | pitches of the tuning, same order as in Guitar.js' stringedTunings, i.e. low to high notes |
### instruments/Guitar.getTuningPitchRange(tuning, fretCount) ⇒ Array.<number>
Returns the pitch range of a tuning, given the number of frets.
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: Array.<number> - [minPitch, maxPitch]
| Param | Type | Description |
| --- | --- | --- |
| tuning | StringedTuning | tuning |
| fretCount | number | number of frets the instrument has (default: 24) |
### instruments/Guitar.getPitchFromFretboardPos(string, fret, tuning) ⇒ number
Returns the pitch of a note at a given fretboard position.
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: number - pitch
| Param | Type | Description |
| --- | --- | --- |
| string | number | string |
| fret | number | fret |
| tuning | StringedTuning | tuning |
### instruments/Guitar.getNoteInfoFromFretboardPos(string, fret, tuning) ⇒ object
Returns MIDI attributes of a note at a given fretboard position, e.g. C#
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: object - note info, e.g. { pitch: 69, name: 'A', octave: 4, label: 'A4', frequency: 440.000 }
| Param | Type | Description |
| --- | --- | --- |
| string | number | string |
| fret | number | fret |
| tuning | StringedTuning | tuning |
### instruments/Guitar.getFretboardPositionsFromPitch(pitch, tuning, fretCount) ⇒ Array.<object>
Finds all fretboard positions with this exact pitch.
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: Array.<object> - positions
| Param | Type | Description |
| --- | --- | --- |
| pitch | number | MIDI pitch |
| tuning | StringedTuning | tuning |
| fretCount | number | number of frets the instrument has |
### instruments/Guitar.getFretboardPositionsFromNoteName(name, tuning, fretCount) ⇒ Array.<object>
Finds all fretboard positions with this note in all octaves.
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: Array.<object> - positions
| Param | Type | Description |
| --- | --- | --- |
| name | string | note name, e.g. 'C#' |
| tuning | StringedTuning | tuning |
| fretCount | number | number of frets the instrument has |
### instruments/Guitar.generateExampleData(startTime, count, tuning) ⇒ [Array.<GuitarNote>](#GuitarNote)
Generates example MIDI-like data (preprocessed MIDI).
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: [Array.<GuitarNote>](#GuitarNote) - notes
| Param | Type | Description |
| --- | --- | --- |
| startTime | number | start tick |
| count | number | number of notes to generate |
| tuning | StringedTuning | tuning |
### instruments/Guitar.fretboardPositionsFromMidi(notes, tuning, fretCount) ⇒ [Array.<GuitarNote>](#GuitarNote)
Estimates the fretboard position from MIDI notes
**Kind**: static method of [instruments/Guitar](#module_instruments/Guitar)
**Returns**: [Array.<GuitarNote>](#GuitarNote) - GuitarNotes with fretboard positions
**Todo**
- [ ] does not work well yet
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes with only MIDI information |
| tuning | StringedTuning | tuning |
| fretCount | number | number of frets the instrument has |
## instruments/Lamellophone
* [instruments/Lamellophone](#module_instruments/Lamellophone)
* [.LamellophoneTuning](#module_instruments/Lamellophone.LamellophoneTuning)
* [new exports.LamellophoneTuning(name, notes)](#new_module_instruments/Lamellophone.LamellophoneTuning_new)
* [.getNumbers()](#module_instruments/Lamellophone.LamellophoneTuning+getNumbers) ⇒ Array.<string>
* [.getLetters()](#module_instruments/Lamellophone.LamellophoneTuning+getLetters) ⇒ Array.<string>
* [.lamellophoneTunings](#module_instruments/Lamellophone.lamellophoneTunings) : Map.<string, Map.<string, LamellophoneTuning>>
* [.convertTabToNotes(tab, tuning, tempo)](#module_instruments/Lamellophone.convertTabToNotes) ⇒ [Array.<Note>](#Note)
* [.convertNotesToTab(notes, tuning, mode, restSize)](#module_instruments/Lamellophone.convertNotesToTab) ⇒ string
* [.convertNotesToHtmlTab(notes, tuning, mode, restSize, colormap)](#module_instruments/Lamellophone.convertNotesToHtmlTab) ⇒ string
* [.convertNumbersToLetters(numberTab, numberLetterMap)](#module_instruments/Lamellophone.convertNumbersToLetters) ⇒ string
* [.bestTransposition(notes, tuning)](#module_instruments/Lamellophone.bestTransposition) ⇒ object
### instruments/Lamellophone.LamellophoneTuning
Represents Lamellophone tunings
**Kind**: static class of [instruments/Lamellophone](#module_instruments/Lamellophone)
* [.LamellophoneTuning](#module_instruments/Lamellophone.LamellophoneTuning)
* [new exports.LamellophoneTuning(name, notes)](#new_module_instruments/Lamellophone.LamellophoneTuning_new)
* [.getNumbers()](#module_instruments/Lamellophone.LamellophoneTuning+getNumbers) ⇒ Array.<string>
* [.getLetters()](#module_instruments/Lamellophone.LamellophoneTuning+getLetters) ⇒ Array.<string>
#### new exports.LamellophoneTuning(name, notes)
Represents a tuning of lamellophone.
| Param | Type | Description |
| --- | --- | --- |
| name | string | name |
| notes | Array.<string> | array of notes, same order as on instrument e.g. [..., 'D4','C4', 'F#4', ...] |
#### lamellophoneTuning.getNumbers() ⇒ Array.<string>
Returns an array of the tuning's notes as number representation:
Tuning notes: C4, D4, ... C5, D5, ... C6, D6
Number format: 1, 2, ... 1°, 2°, ... 1°°, 2°°
**Kind**: instance method of [LamellophoneTuning](#module_instruments/Lamellophone.LamellophoneTuning)
**Returns**: Array.<string> - array with tuning notes in number representation
#### lamellophoneTuning.getLetters() ⇒ Array.<string>
Returns an array of the tuning's notes as letter representation:
Tuning notes: C4, D4, ... C5, D5, ... C6, D6
Number format: C, D, ... C°, D°, ... C°°, D°°
**Kind**: instance method of [LamellophoneTuning](#module_instruments/Lamellophone.LamellophoneTuning)
**Returns**: Array.<string> - array with tuning notes in letter representation
### instruments/Lamellophone.lamellophoneTunings : Map.<string, Map.<string, LamellophoneTuning>>
Tunings.
Notes are in the same order as on the instrument
**Kind**: static constant of [instruments/Lamellophone](#module_instruments/Lamellophone)
### instruments/Lamellophone.convertTabToNotes(tab, tuning, tempo) ⇒ [Array.<Note>](#Note)
Parses a tab into notes
**Kind**: static method of [instruments/Lamellophone](#module_instruments/Lamellophone)
**Returns**: [Array.<Note>](#Note) - notes
| Param | Type | Description |
| --- | --- | --- |
| tab | string | in letter format |
| tuning | LamellophoneTuning | tuning |
| tempo | number | tempo in bpm |
### instruments/Lamellophone.convertNotesToTab(notes, tuning, mode, restSize) ⇒ string
Converts an array of notes into a text tab
**Kind**: static method of [instruments/Lamellophone](#module_instruments/Lamellophone)
**Returns**: string - text tab
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| tuning | LamellophoneTuning | tuning |
| mode | 'letter' \| 'number' | mode |
| restSize | number | number of seconds for a gap between chords to insert a line break |
### instruments/Lamellophone.convertNotesToHtmlTab(notes, tuning, mode, restSize, colormap) ⇒ string
Converts an array of notes into an HTML tab with colored notes
**Kind**: static method of [instruments/Lamellophone](#module_instruments/Lamellophone)
**Returns**: string - HTML tab
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| tuning | LamellophoneTuning | tuning |
| mode | 'letter' \| 'number' | mode |
| restSize | number | number of seconds for a gap between chords to insert a line break |
| colormap | function | color map function: pitch to color |
### instruments/Lamellophone.convertNumbersToLetters(numberTab, numberLetterMap) ⇒ string
Converts a number-based tab to note letter format
**Kind**: static method of [instruments/Lamellophone](#module_instruments/Lamellophone)
**Returns**: string - tab in letter format
| Param | Type | Description |
| --- | --- | --- |
| numberTab | string | tab text with number format |
| numberLetterMap | Map.<number, string> | maps numbers to letters |
### instruments/Lamellophone.bestTransposition(notes, tuning) ⇒ object
Tries to find a transposition s.t. the tuning is able to play all notes.
If not not possible, return the transposition that requires the least keys to
be retuned.
**Kind**: static method of [instruments/Lamellophone](#module_instruments/Lamellophone)
**Returns**: object - {transpose: number, retune: Map}
**Todo**
- [ ] tests fail
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| tuning | LamellophoneTuning | tuning |
## instruments/Piano
### instruments/Piano.pianoPitchRange : Map.<number, object>
Map:keyCount->pitchRange
pitchRange is {minPitch:number, maxPitch:number}
**Kind**: static constant of [instruments/Piano](#module_instruments/Piano)
## stringBased/Gotoh
* [stringBased/Gotoh](#module_stringBased/Gotoh)
* [.gotoh(seqA, seqB, similarityFunction, gapPenaltyStart, gapPenaltyExtend)](#module_stringBased/Gotoh.gotoh) ⇒ number
* [.normalizedGotoh(seqA, seqB, similarityFunction, gapPenaltyStart, gapPenaltyExtend)](#module_stringBased/Gotoh.normalizedGotoh) ⇒ number
* [.matchMissmatchSimilarity(a, b)](#module_stringBased/Gotoh.matchMissmatchSimilarity) ⇒ number
* [.differenceSimilarity(a, b)](#module_stringBased/Gotoh.differenceSimilarity) ⇒ number
### stringBased/Gotoh.gotoh(seqA, seqB, similarityFunction, gapPenaltyStart, gapPenaltyExtend) ⇒ number
Calculates the SIMILARITY for two strings or arrays.
Similar to NeedlemanWunsch but O(n^2) instead of O(n^3)
IMPORTANT: This metric is not symmetric!
**Kind**: static method of [stringBased/Gotoh](#module_stringBased/Gotoh)
**Returns**: number - similarity score
**See**: https://de.wikipedia.org/wiki/Gotoh-Algorithmus
**Todo**
- [ ] normalize to [0, 1], but how?
- [ ] somehow the the matched sequences and gaps...
| Param | Type | Description |
| --- | --- | --- |
| seqA | string \| Array | a sequence |
| seqB | string \| Array | a sequence |
| similarityFunction | function | a function that takes two elements and returns their similarity score (higher => more similar) (a:any, b:any):number |
| gapPenaltyStart | number | cost for starting a new gap (negative) |
| gapPenaltyExtend | number | cost for continuing a gap (negative) |
### stringBased/Gotoh.normalizedGotoh(seqA, seqB, similarityFunction, gapPenaltyStart, gapPenaltyExtend) ⇒ number
Idea: what would the max. similarity value be? the string with itself!
So just compare the longer string to itself and use that similarity to
normalize
**Kind**: static method of [stringBased/Gotoh](#module_stringBased/Gotoh)
**Returns**: number - normalized similarity score
**Todo**
- [ ] does this work with negative costs and/or results?
- [ ] can this be optimized since only the similarityFunction is needed?
- [ ] only compute 'a' matrix for maxSimilarity
| Param | Type | Description |
| --- | --- | --- |
| seqA | string \| Array | a sequence |
| seqB | string \| Array | a sequence |
| similarityFunction | function | a function that takes two elements and returns their similarity score (higher => more similar) (a:any, b:any):number |
| gapPenaltyStart | number | cost for starting a new gap (negative) |
| gapPenaltyExtend | number | cost for continuing a gap (negative) |
### stringBased/Gotoh.matchMissmatchSimilarity(a, b) ⇒ number
Cost function that simply checks whether two values are equal or not with ===
**Kind**: static method of [stringBased/Gotoh](#module_stringBased/Gotoh)
**Returns**: number - 1 if equal, -1 otherwise
| Param | Type | Description |
| --- | --- | --- |
| a | any | some value |
| b | any | some value |
### stringBased/Gotoh.differenceSimilarity(a, b) ⇒ number
Cost function that takes the negative absolute value of the value's
difference, assuming that close values are more similar
**Kind**: static method of [stringBased/Gotoh](#module_stringBased/Gotoh)
**Returns**: number - -Math.abs(a - b)
| Param | Type | Description |
| --- | --- | --- |
| a | number | some value |
| b | number | some value |
## stringBased
**Todo**
- [ ] rename to Sequences
## stringBased/Levenshtein
* [stringBased/Levenshtein](#module_stringBased/Levenshtein)
* [.levenshtein(a, b, normalize)](#module_stringBased/Levenshtein.levenshtein) ⇒ number
* [.damerauLevenshtein(a, b, normalize)](#module_stringBased/Levenshtein.damerauLevenshtein) ⇒ number
### stringBased/Levenshtein.levenshtein(a, b, normalize) ⇒ number
Computes the Levenshtein distance of two strings or arrays.
**Kind**: static method of [stringBased/Levenshtein](#module_stringBased/Levenshtein)
**Returns**: number - Levenshtein distance
**See**: https://gist.github.com/andrei-m/982927#gistcomment-1931258
**Author**: https://github.com/kigiri, license: MIT
| Param | Type | Description |
| --- | --- | --- |
| a | string \| Array | a string |
| b | string \| Array | another string |
| normalize | boolean | when set to true, the distance will be normalized to [0, 1], by dividing by the longer string's length |
### stringBased/Levenshtein.damerauLevenshtein(a, b, normalize) ⇒ number
Computes the Damerau-Levenshtein distance of two strings or arrays.
**Kind**: static method of [stringBased/Levenshtein](#module_stringBased/Levenshtein)
**Returns**: number - Levenshtein distance
**See**: https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance
| Param | Type | Description |
| --- | --- | --- |
| a | string \| Array | a string |
| b | string \| Array | another string |
| normalize | boolean | when set to true, the distance will be normalized to [0, 1], by dividing by the longer string's length |
## stringBased/LongestCommonSubsequence
* [stringBased/LongestCommonSubsequence](#module_stringBased/LongestCommonSubsequence)
* [.lcs(a, b)](#module_stringBased/LongestCommonSubsequence.lcs) ⇒ string \| Array
* [.lcsLength(a, b)](#module_stringBased/LongestCommonSubsequence.lcsLength) ⇒ number
* [.normalizedLcsLength(a, b)](#module_stringBased/LongestCommonSubsequence.normalizedLcsLength) ⇒ number
### stringBased/LongestCommonSubsequence.lcs(a, b) ⇒ string \| Array
Calculates the longest common subsequence.
**Kind**: static method of [stringBased/LongestCommonSubsequence](#module_stringBased/LongestCommonSubsequence)
**Returns**: string \| Array - the longest common subsequence
**See**: https://rosettacode.org/wiki/Longest_common_subsequence#JavaScript
| Param | Type | Description |
| --- | --- | --- |
| a | string \| Array | a string |
| b | string \| Array | another string |
**Example**
```js
const lcs = StringBased.LongestCommonSubsequence.lcs('hello world!', 'world');
// world
```
### stringBased/LongestCommonSubsequence.lcsLength(a, b) ⇒ number
Calculates the *length* of the longest common subsequence.
Also works with arrays.
**Kind**: static method of [stringBased/LongestCommonSubsequence](#module_stringBased/LongestCommonSubsequence)
**Returns**: number - the length of longest common subsequence
**See**: https://rosettacode.org/wiki/Longest_common_subsequence#JavaScript
| Param | Type | Description |
| --- | --- | --- |
| a | string \| Array | a string |
| b | string \| Array | another string |
**Example**
```js
const lcsLength = StringBased.LongestCommonSubsequence.lcs('hello world!', 'world');
// 5
```
### stringBased/LongestCommonSubsequence.normalizedLcsLength(a, b) ⇒ number
Normalizes the result of lcsLength() by dividing by the longer string's
length.
**Kind**: static method of [stringBased/LongestCommonSubsequence](#module_stringBased/LongestCommonSubsequence)
**Returns**: number - normalized length of longest common subsequence
| Param | Type | Description |
| --- | --- | --- |
| a | string \| Array | a string |
| b | string \| Array | another string |
## stringBased/NeedlemanWunsch
* [stringBased/NeedlemanWunsch](#module_stringBased/NeedlemanWunsch)
* [~NeedlemanWunsch](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch)
* [new NeedlemanWunsch(seq1, seq2, matchScore, mismatchPenalty, gapPenalty)](#new_module_stringBased/NeedlemanWunsch..NeedlemanWunsch_new)
* [.calcScoresAndTracebacks()](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch+calcScoresAndTracebacks)
* [.alignmentChildren(pos)](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch+alignmentChildren) ⇒ Array.<object>
* [.alignmentTraceback()](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch+alignmentTraceback) ⇒ Array.<object>
### stringBased/NeedlemanWunsch~NeedlemanWunsch
Needleman-Wunsch algorithm
**Kind**: inner class of [stringBased/NeedlemanWunsch](#module_stringBased/NeedlemanWunsch)
**See**: https://github.com/blievrouw/needleman-wunsch/blob/master/src/needleman_wunsch.js
**Todo**
- [ ] does not support cost matrix
- [ ] extend by matchMismathFunction
* [~NeedlemanWunsch](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch)
* [new NeedlemanWunsch(seq1, seq2, matchScore, mismatchPenalty, gapPenalty)](#new_module_stringBased/NeedlemanWunsch..NeedlemanWunsch_new)
* [.calcScoresAndTracebacks()](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch+calcScoresAndTracebacks)
* [.alignmentChildren(pos)](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch+alignmentChildren) ⇒ Array.<object>
* [.alignmentTraceback()](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch+alignmentTraceback) ⇒ Array.<object>
#### new NeedlemanWunsch(seq1, seq2, matchScore, mismatchPenalty, gapPenalty)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| seq1 | string \| Array | | a string |
| seq2 | string \| Array | | another string |
| matchScore | number | 1 | score for matching characters |
| mismatchPenalty | number | | penalty for mismatching characters |
| gapPenalty | number | | penalty for a gap |
#### needlemanWunsch.calcScoresAndTracebacks()
Calculates (intermediate) scores and tracebacks using provided parameters
**Kind**: instance method of [NeedlemanWunsch](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch)
#### needlemanWunsch.alignmentChildren(pos) ⇒ Array.<object>
Finds next alignment locations (children) from a position in scoring matrix
**Kind**: instance method of [NeedlemanWunsch](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch)
**Returns**: Array.<object> - children - Children positions and alignment types
| Param | Type | Description |
| --- | --- | --- |
| pos | Array.<number> | m- Position in scoring matrix |
#### needlemanWunsch.alignmentTraceback() ⇒ Array.<object>
Runs through scoring matrix from bottom-right to top-left using traceback values to create all optimal alignments
**Kind**: instance method of [NeedlemanWunsch](#module_stringBased/NeedlemanWunsch..NeedlemanWunsch)
**Returns**: Array.<object> - e.g. [{ seq1: '-4321', seq2: '54321' }]
## stringBased/SuffixTree
* [stringBased/SuffixTree](#module_stringBased/SuffixTree)
* [~SuffixTree](#module_stringBased/SuffixTree..SuffixTree)
* [new SuffixTree(array)](#new_module_stringBased/SuffixTree..SuffixTree_new)
* [.getLongestRepeatedSubString()](#module_stringBased/SuffixTree..SuffixTree+getLongestRepeatedSubString) ⇒ Array
* [.toString()](#module_stringBased/SuffixTree..SuffixTree+toString) ⇒ string
* [.toJson()](#module_stringBased/SuffixTree..SuffixTree+toJson) ⇒ string
* [~TreeNode](#module_stringBased/SuffixTree..TreeNode)
* [.checkNodes(suf)](#module_stringBased/SuffixTree..TreeNode+checkNodes) ⇒ boolean
* [.checkLeaves(suf)](#module_stringBased/SuffixTree..TreeNode+checkLeaves)
* [.addSuffix(suf)](#module_stringBased/SuffixTree..TreeNode+addSuffix)
* [.getLongestRepeatedSubString()](#module_stringBased/SuffixTree..TreeNode+getLongestRepeatedSubString) ⇒ Array
* [.toString(indent)](#module_stringBased/SuffixTree..TreeNode+toString) ⇒ string
### stringBased/SuffixTree~SuffixTree
Suffix tree, a tree that shows which subsequences are repeated
**Kind**: inner class of [stringBased/SuffixTree](#module_stringBased/SuffixTree)
**See**: https://github.com/eikes/suffixtree/blob/master/js/suffixtree.js
* [~SuffixTree](#module_stringBased/SuffixTree..SuffixTree)
* [new SuffixTree(array)](#new_module_stringBased/SuffixTree..SuffixTree_new)
* [.getLongestRepeatedSubString()](#module_stringBased/SuffixTree..SuffixTree+getLongestRepeatedSubString) ⇒ Array
* [.toString()](#module_stringBased/SuffixTree..SuffixTree+toString) ⇒ string
* [.toJson()](#module_stringBased/SuffixTree..SuffixTree+toJson) ⇒ string
#### new SuffixTree(array)
SuffixTree for strings or Arrays
| Param | Type | Description |
| --- | --- | --- |
| array | string \| Array | string or Array to process |
#### suffixTree.getLongestRepeatedSubString() ⇒ Array
Returns the longest repeated substring
**Kind**: instance method of [SuffixTree](#module_stringBased/SuffixTree..SuffixTree)
**Returns**: Array - longest repeated substring
#### suffixTree.toString() ⇒ string
Returns a readable string format of this tree
**Kind**: instance method of [SuffixTree](#module_stringBased/SuffixTree..SuffixTree)
**Returns**: string - string
#### suffixTree.toJson() ⇒ string
Returns a JSON representation of this tree
**Kind**: instance method of [SuffixTree](#module_stringBased/SuffixTree..SuffixTree)
**Returns**: string - JSON
### stringBased/SuffixTree~TreeNode
TreeNode
**Kind**: inner class of [stringBased/SuffixTree](#module_stringBased/SuffixTree)
* [~TreeNode](#module_stringBased/SuffixTree..TreeNode)
* [.checkNodes(suf)](#module_stringBased/SuffixTree..TreeNode+checkNodes) ⇒ boolean
* [.checkLeaves(suf)](#module_stringBased/SuffixTree..TreeNode+checkLeaves)
* [.addSuffix(suf)](#module_stringBased/SuffixTree..TreeNode+addSuffix)
* [.getLongestRepeatedSubString()](#module_stringBased/SuffixTree..TreeNode+getLongestRepeatedSubString) ⇒ Array
* [.toString(indent)](#module_stringBased/SuffixTree..TreeNode+toString) ⇒ string
#### treeNode.checkNodes(suf) ⇒ boolean
**Kind**: instance method of [TreeNode](#module_stringBased/SuffixTree..TreeNode)
**Returns**: boolean - true if first entry of suf equals the value of a child
| Param | Type | Description |
| --- | --- | --- |
| suf | string \| Array | suffix |
#### treeNode.checkLeaves(suf)
**Kind**: instance method of [TreeNode](#module_stringBased/SuffixTree..TreeNode)
| Param | Type | Description |
| --- | --- | --- |
| suf | string \| Array | suffix |
#### treeNode.addSuffix(suf)
**Kind**: instance method of [TreeNode](#module_stringBased/SuffixTree..TreeNode)
| Param | Type | Description |
| --- | --- | --- |
| suf | string \| Array | suffix |
#### treeNode.getLongestRepeatedSubString() ⇒ Array
Returns the longest repeated substring
**Kind**: instance method of [TreeNode](#module_stringBased/SuffixTree..TreeNode)
**Returns**: Array - longest substring
#### treeNode.toString(indent) ⇒ string
Readable string representation of this node and its children
**Kind**: instance method of [TreeNode](#module_stringBased/SuffixTree..TreeNode)
**Returns**: string - string representation
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| indent | number | 1 | indentation |
## utils/ArrayUtils
* [utils/ArrayUtils](#module_utils/ArrayUtils)
* [.arrayShallowEquals(a, b)](#module_utils/ArrayUtils.arrayShallowEquals) ⇒ boolean
* [.arrayHasSameElements(a, b, checkLength)](#module_utils/ArrayUtils.arrayHasSameElements) ⇒ boolean
* [.count(array, value, [comparator])](#module_utils/ArrayUtils.count) ⇒ number
* [.jaccardIndex(set1, set2)](#module_utils/ArrayUtils.jaccardIndex) ⇒ number
* [.kendallTau(ranking1, ranking2, [normalize])](#module_utils/ArrayUtils.kendallTau) ⇒ number
* [.removeDuplicates(array)](#module_utils/ArrayUtils.removeDuplicates) ⇒ Array
* [.arrayContainsArray(a, b)](#module_utils/ArrayUtils.arrayContainsArray) ⇒ boolean
* [.arraySlicesEqual(a, b, length, [startA], [startB])](#module_utils/ArrayUtils.arraySlicesEqual) ⇒ boolean
* [.arrayIndexOf(haystack, needle, [startIndex])](#module_utils/ArrayUtils.arrayIndexOf) ⇒ number
* [.getArrayMax(array)](#module_utils/ArrayUtils.getArrayMax) ⇒ number
* [.normalizeNdArray(array)](#module_utils/ArrayUtils.normalizeNdArray) ⇒ Array
* [.normalizeNdArrayNegative(array)](#module_utils/ArrayUtils.normalizeNdArrayNegative) ⇒ Array
* [.euclideanDistance(matrixA, matrixB)](#module_utils/ArrayUtils.euclideanDistance) ⇒ number
* [.formatMatrix(matrix, colSeparator, rowSeparator, formatter)](#module_utils/ArrayUtils.formatMatrix) ⇒ string
* [.binarySearch(array, value, accessor)](#module_utils/ArrayUtils.binarySearch) ⇒ \*
* [.findStreaks(values, accessor, equality)](#module_utils/ArrayUtils.findStreaks) ⇒ Array.<object>
* [.findRepeatedIndices(sequence, equals)](#module_utils/ArrayUtils.findRepeatedIndices) ⇒ Array.<number>
### utils/ArrayUtils.arrayShallowEquals(a, b) ⇒ boolean
Shallow compares two arrays
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: boolean - true iff equal
| Param | Type | Description |
| --- | --- | --- |
| a | Array | an array |
| b | Array | another array |
### utils/ArrayUtils.arrayHasSameElements(a, b, checkLength) ⇒ boolean
Checks if two arrays contain the same elements,
ignoring their ordering in each array.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: boolean - true iff arrays contain same elements
| Param | Type | Description |
| --- | --- | --- |
| a | Array | an array |
| b | Array | another array |
| checkLength | boolean | also checks if arrays have the same length |
### utils/ArrayUtils.count(array, value, [comparator]) ⇒ number
Counts how often value appears in array
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: number - count
**Todo**
- [ ] use the one from mvlib, already moved there
| Param | Type | Description |
| --- | --- | --- |
| array | Array | array |
| value | \* | value |
| [comparator] | function | comparator function, can be undefined to just use ===. Comparator has to return true when values are regarded as equal |
### utils/ArrayUtils.jaccardIndex(set1, set2) ⇒ number
Jaccard index calulates the similarity of the sets as the size of the set
interaction divided by the size of the set union:
jackard_index = |intersection| / |union|
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: number - similarity in [0, 1]
**See**: https://en.wikipedia.org/wiki/Jaccard_index
| Param | Type | Description |
| --- | --- | --- |
| set1 | Array.<number> | set 1 |
| set2 | Array.<number> | set 2 |
### utils/ArrayUtils.kendallTau(ranking1, ranking2, [normalize]) ⇒ number
Kendall Tau distance
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: number - Kendall tau distance
**Throws**:
- 'Ranking length must be equal' if rankings don't have euqal length
**See**: https://en.wikipedia.org/wiki/Kendall_tau_distance
**Todo**
- [ ] naive implementation, can be sped up with hints on Wikipedia,
see also https://stackoverflow.com/questions/6523712/calculating-the-number-of-inversions-in-a-permutation/6523781#6523781
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| ranking1 | Array.<number> | | a ranking, i.e. for each entry the rank |
| ranking2 | Array.<number> | | a ranking, i.e. for each entry the rank |
| [normalize] | boolean | true | normalize to [0, 1]? |
### utils/ArrayUtils.removeDuplicates(array) ⇒ Array
Removes duplicates from an Array by converting to a Set and back
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: Array - array without duplicates
| Param | Type | Description |
| --- | --- | --- |
| array | Array | an array |
### utils/ArrayUtils.arrayContainsArray(a, b) ⇒ boolean
Checks whether the array a contains the array b, i.e. whether the first
b.length elements are the same.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: boolean - true iff a contains b
**Todo**
- [ ] rename to arrayStartsWithArray
| Param | Type | Description |
| --- | --- | --- |
| a | Array | an array |
| b | Array | a shorter array |
### utils/ArrayUtils.arraySlicesEqual(a, b, length, [startA], [startB]) ⇒ boolean
Compares a slice of a with a slice of b.
Slices start at startA and startB and have the same length
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: boolean - true if slices are equal
**Throws**:
- 'undefined length' length is undefined
- 'start < 0' when start is negative
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| a | Array | | an Array |
| b | Array | | an Array |
| length | number | | slice length |
| [startA] | number | 0 | start index for the slice in a to compare |
| [startB] | number | 0 | start index for the slice in b to compare |
### utils/ArrayUtils.arrayIndexOf(haystack, needle, [startIndex]) ⇒ number
Finds an array in another array, only shallow comparison
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: number - index or -1 when not found
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| haystack | Array | | array to search in |
| needle | Array | | array to search for |
| [startIndex] | number | 0 | index from which to start searching |
### utils/ArrayUtils.getArrayMax(array) ⇒ number
Returns the maximum numerical value from an array of arrays with arbitrary
depth and structure.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: number - maximum value
| Param | Type | Description |
| --- | --- | --- |
| array | Array | array |
### utils/ArrayUtils.normalizeNdArray(array) ⇒ Array
Normalizes by dividing all entries by the maximum.
Only for positive values! Assumes 0 to be the minimum.
Use normalizeNdArrayNegative for arbitrary numbers.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: Array - normalized array
**See**: normalizeNdArrayNegative
| Param | Type | Description |
| --- | --- | --- |
| array | Array | nD array with arbitrary depth and structure |
### utils/ArrayUtils.normalizeNdArrayNegative(array) ⇒ Array
Normalizes by dividing scaling all values to [0, 1] linearly.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: Array - normalized array
**Todo**
- [ ] move to musicvis-lib and test
| Param | Type | Description |
| --- | --- | --- |
| array | Array | nD array with arbitrary depth and structure, containing only numbers |
### utils/ArrayUtils.euclideanDistance(matrixA, matrixB) ⇒ number
Assumes same shape of matrices.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: number - Euclidean distance of the two matrices
| Param | Type | Description |
| --- | --- | --- |
| matrixA | Array.<Array.<number>> | a matrix |
| matrixB | Array.<Array.<number>> | a matrix |
### utils/ArrayUtils.formatMatrix(matrix, colSeparator, rowSeparator, formatter) ⇒ string
Stringifies a 2D array / matrix for logging onto the console.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: string - stringified matrix
| Param | Type | Description |
| --- | --- | --- |
| matrix | Array.<Array.<any>> | the matrix |
| colSeparator | string | column separator |
| rowSeparator | string | row separator |
| formatter | function | formatting for each element |
### utils/ArrayUtils.binarySearch(array, value, accessor) ⇒ \*
Returns the value in array that is closest to value.
Array MUST be sorted ascending.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: \* - value in array closest to value
| Param | Type | Description |
| --- | --- | --- |
| array | Array | array |
| value | \* | value |
| accessor | function | accessor |
### utils/ArrayUtils.findStreaks(values, accessor, equality) ⇒ Array.<object>
Finds streaks of values in an array.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: Array.<object> - {startIndex, endIndex, length}[]
| Param | Type | Description |
| --- | --- | --- |
| values | Array | array |
| accessor | function | value to compare |
| equality | function | comparator for equality of two values |
**Example**
```js
const arr = [1, 1, 2, 3, 3, 3];
const streaks = findStreaks(arr);
```
### utils/ArrayUtils.findRepeatedIndices(sequence, equals) ⇒ Array.<number>
For each element in a sequence, finds the lowest index where an equal element
occurs.
**Kind**: static method of [utils/ArrayUtils](#module_utils/ArrayUtils)
**Returns**: Array.<number> - result
| Param | Type | Description |
| --- | --- | --- |
| sequence | Array | an Array |
| equals | function | euqality function |
## utils/BlobUtils
* [utils/BlobUtils](#module_utils/BlobUtils)
* [.blobToBase64(blob)](#module_utils/BlobUtils.blobToBase64) ⇒ Promise.<string, undefined>
* [.blobToFileExtension(blob)](#module_utils/BlobUtils.blobToFileExtension) ⇒ string
### utils/BlobUtils.blobToBase64(blob) ⇒ Promise.<string, undefined>
Converts a Blob to a base64 string
**Kind**: static method of [utils/BlobUtils](#module_utils/BlobUtils)
**Returns**: Promise.<string, undefined> - base64 string
| Param | Type | Description |
| --- | --- | --- |
| blob | Blob | Blob |
### utils/BlobUtils.blobToFileExtension(blob) ⇒ string
Extracts the file extension from a Blob, so it can be saved as a file with
an appropriate extension.
**Kind**: static method of [utils/BlobUtils](#module_utils/BlobUtils)
**Returns**: string - file extension
| Param | Type | Description |
| --- | --- | --- |
| blob | Blob | Blob |
## utils/FormattingUtils
* [utils/FormattingUtils](#module_utils/FormattingUtils)
* [.formatTime(seconds, includeMillis)](#module_utils/FormattingUtils.formatTime) ⇒ string
* [.formatDate(date, replaceT, keepMillis)](#module_utils/FormattingUtils.formatDate) ⇒ string
* [.formatSongTitle(title, maxLength)](#module_utils/FormattingUtils.formatSongTitle) ⇒ string
### utils/FormattingUtils.formatTime(seconds, includeMillis) ⇒ string
Formats a time in seconds to utils/FormattingUtils](#module_utils/FormattingUtils)
**Returns**: string - 0-padded time string number \| null | in seconds |
| includeMillis | boolean | include milli seconds in string? |
### utils/FormattingUtils.formatDate(date, replaceT, keepMillis) ⇒ string
Formats a Date to a string with format
YYYY-mm-DDTHH:MM:SS
or when replaceT == true
YYYY-mm-DD HH:MM:SS
**Kind**: static method of [utils/FormattingUtils](#module_utils/FormattingUtils)
**Returns**: string - formatted date
| Param | Type | Description |
| --- | --- | --- |
| date | Date | date |
| replaceT | boolean | replace the 'T'? |
| keepMillis | boolean | keep milliseconds? |
### utils/FormattingUtils.formatSongTitle(title, maxLength) ⇒ string
Formats the song title (e.g. remove file extension and shorten)
**Kind**: static method of [utils/FormattingUtils](#module_utils/FormattingUtils)
**Returns**: string - formatted song title
| Param | Type | Description |
| --- | --- | --- |
| title | string | song title |
| maxLength | number | shorten to this length |
## utils
## utils/LocalStorageUtils
* [utils/LocalStorageUtils](#module_utils/LocalStorageUtils)
* [.storeObjectInLocalStorage(key, object)](#module_utils/LocalStorageUtils.storeObjectInLocalStorage)
* [.getObjectFromLocalStorage(key)](#module_utils/LocalStorageUtils.getObjectFromLocalStorage) ⇒ object \| null
### utils/LocalStorageUtils.storeObjectInLocalStorage(key, object)
Stringifies an object and stores it in the localStorage
**Kind**: static method of [utils/LocalStorageUtils](#module_utils/LocalStorageUtils)
| Param | Type | Description |
| --- | --- | --- |
| key | string | key |
| object | object | JSON compatible object |
### utils/LocalStorageUtils.getObjectFromLocalStorage(key) ⇒ object \| null
Retrieves a stringified object from the localStorage and parses it.
**Kind**: static method of [utils/LocalStorageUtils](#module_utils/LocalStorageUtils)
**Returns**: object \| null - object or null of not possible
| Param | Type | Description |
| --- | --- | --- |
| key | string | key |
## utils/MathUtils
* [utils/MathUtils](#module_utils/MathUtils)
* [.randFloat(min, max)](#module_utils/MathUtils.randFloat) ⇒ number
* [.choose(array)](#module_utils/MathUtils.choose) ⇒ any
* [.clipValue(value, minValue, maxValue)](#module_utils/MathUtils.clipValue) ⇒ number
* [.roundToNDecimals(number, n)](#module_utils/MathUtils.roundToNDecimals) ⇒ number
* [.swapSoSmallerFirst(x, y)](#module_utils/MathUtils.swapSoSmallerFirst) ⇒ Array.<number>
* [.countOnesOfBinary(integer)](#module_utils/MathUtils.countOnesOfBinary) ⇒ number
* [.findLocalMaxima(array)](#module_utils/MathUtils.findLocalMaxima) ⇒ Array.<number>
### utils/MathUtils.randFloat(min, max) ⇒ number
Generates a random float in [min, max)
**Kind**: static method of [utils/MathUtils](#module_utils/MathUtils)
**Returns**: number - random float
| Param | Type | Description |
| --- | --- | --- |
| min | number | minimum |
| max | number | maximum |
### utils/MathUtils.choose(array) ⇒ any
Returns a random element from the given array.
**Kind**: static method of [utils/MathUtils](#module_utils/MathUtils)
**Returns**: any - random element from the array
| Param | Type | Description |
| --- | --- | --- |
| array | Array | an array |
### utils/MathUtils.clipValue(value, minValue, maxValue) ⇒ number
Shortcut for Math.max(minValue, Math.min(maxValue, value))
**Kind**: static method of [utils/MathUtils](#module_utils/MathUtils)
**Returns**: number - clipped number
| Param | Type | Description |
| --- | --- | --- |
| value | number | value |
| minValue | number | lower limit |
| maxValue | number | upper limit |
### utils/MathUtils.roundToNDecimals(number, n) ⇒ number
Rounds a number to a given number of decimals
**Kind**: static method of [utils/MathUtils](#module_utils/MathUtils)
**Returns**: number - rounded number
| Param | Type | Description |
| --- | --- | --- |
| number | number | a number |
| n | number | number of digits |
### utils/MathUtils.swapSoSmallerFirst(x, y) ⇒ Array.<number>
Swaps two numbers if the first is larger than the second
**Kind**: static method of [utils/MathUtils](#module_utils/MathUtils)
**Returns**: Array.<number> - array with the smaller number first
| Param | Type | Description |
| --- | --- | --- |
| x | number | a number |
| y | number | a number |
### utils/MathUtils.countOnesOfBinary(integer) ⇒ number
Counts the number of 1s in a binary number, e.g 100101 has 3 1s
**Kind**: static method of [utils/MathUtils](#module_utils/MathUtils)
**Returns**: number - number of 1s
**See**: https://prismoskills.appspot.com/lessons/Bitwise_Operators/Count_ones_in_an_integer.jsp
| Param | Type | Description |
| --- | --- | --- |
| integer | number | an integer number |
### utils/MathUtils.findLocalMaxima(array) ⇒ Array.<number>
Local maxima are found by looking at entries that are higher than their left
and right neighbor, or higher than their only neighbor if they are at the
boundary.
IMPORTANT: does not find plateaus
**Kind**: static method of [utils/MathUtils](#module_utils/MathUtils)
**Returns**: Array.<number> - array with indices of maxima
| Param | Type | Description |
| --- | --- | --- |
| array | Array.<number> | array |
## utils/MiscUtils
* [utils/MiscUtils](#module_utils/MiscUtils)
* [.deepCloneFlatObjectMap(map)](#module_utils/MiscUtils.deepCloneFlatObjectMap) ⇒ Map
* [.groupNotesByPitch(tracks)](#module_utils/MiscUtils.groupNotesByPitch) ⇒ Map
* [.reverseString(s)](#module_utils/MiscUtils.reverseString) ⇒ string
* [.findNearest(notes, targetNote)](#module_utils/MiscUtils.findNearest) ⇒ [Note](#Note)
* [.delay(seconds)](#module_utils/MiscUtils.delay) ⇒ Promise
### utils/MiscUtils.deepCloneFlatObjectMap(map) ⇒ Map
Clones a map where the values are flat objects,
i.e. values do not contain objects themselfes.
**Kind**: static method of [utils/MiscUtils](#module_utils/MiscUtils)
**Returns**: Map - a copy of the map with copies of the value objects
| Param | Type | Description |
| --- | --- | --- |
| map | Map | a map with object values |
### utils/MiscUtils.groupNotesByPitch(tracks) ⇒ Map
Groups the Notes from multiple tracks
**Kind**: static method of [utils/MiscUtils](#module_utils/MiscUtils)
**Returns**: Map - grouping
| Param | Type | Description |
| --- | --- | --- |
| tracks | Array.<Array.<Note>> | array of arrays of Note objects |
### utils/MiscUtils.reverseString(s) ⇒ string
Reverses a given string.
**Kind**: static method of [utils/MiscUtils](#module_utils/MiscUtils)
**Returns**: string - reversed string
| Param | Type | Description |
| --- | --- | --- |
| s | string | string |
### utils/MiscUtils.findNearest(notes, targetNote) ⇒ [Note](#Note)
Given some notes and a target note, finds
the note that has its start time closest to
the one of targetNote
**Kind**: static method of [utils/MiscUtils](#module_utils/MiscUtils)
**Returns**: [Note](#Note) - closest note to targetNote
**Todo**
- [ ] replace by d3 argmin or sth?
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| targetNote | [Note](#Note) | target note |
### utils/MiscUtils.delay(seconds) ⇒ Promise
Allows to wait for a number of seconds with async/await
IMPORTANT: This it not exact, it will at *least* wait for X seconds
**Kind**: static method of [utils/MiscUtils](#module_utils/MiscUtils)
**Returns**: Promise - empty Promise that will resolve after the specified amount
of seconds
| Param | Type | Description |
| --- | --- | --- |
| seconds | number | number of seconds to wait |
## utils/MusicUtils
* [utils/MusicUtils](#module_utils/MusicUtils)
* [.CIRCLE_OF_5THS](#module_utils/MusicUtils.CIRCLE_OF_5THS) : Array.<Array.<any>>
* [.INTERVALS](#module_utils/MusicUtils.INTERVALS) : Map.<number, string>
* [.bpmToSecondsPerBeat(bpm)](#module_utils/MusicUtils.bpmToSecondsPerBeat) ⇒ number
* [.freqToApproxMidiNr(frequency)](#module_utils/MusicUtils.freqToApproxMidiNr) ⇒ number
* [.midiToFrequency(midi)](#module_utils/MusicUtils.midiToFrequency) ⇒ number
* [.chordToInteger(notes)](#module_utils/MusicUtils.chordToInteger) ⇒ number
* [.chordIntegerJaccardIndex(chord1, chord2)](#module_utils/MusicUtils.chordIntegerJaccardIndex) ⇒ number
* [.noteDurationToNoteType(duration, bpm)](#module_utils/MusicUtils.noteDurationToNoteType) ⇒ object
* [.metronomeTrackFromTempoAndMeter(tempo, meter, duration)](#module_utils/MusicUtils.metronomeTrackFromTempoAndMeter) ⇒ Array.<object>
* [.metronomeTrackFromMusicPiece(musicPiece, [tempoFactor])](#module_utils/MusicUtils.metronomeTrackFromMusicPiece) ⇒ Array.<object>
### utils/MusicUtils.CIRCLE\_OF\_5THS : Array.<Array.<any>>
Circle of 5ths as
[midiNr, noteAsSharp, noteAsFlat, numberOfSharps, numberOfFlats]
**Kind**: static constant of [utils/MusicUtils](#module_utils/MusicUtils)
**See**: https://en.wikipedia.org/wiki/Circle_of_fifths
### utils/MusicUtils.INTERVALS : Map.<number, string>
Maps number of semitones to interval name
m - minor
M - major
P - perfect
aug - augmented
**Kind**: static constant of [utils/MusicUtils](#module_utils/MusicUtils)
### utils/MusicUtils.bpmToSecondsPerBeat(bpm) ⇒ number
Converts beats per minute to seconds per beat
**Kind**: static method of [utils/MusicUtils](#module_utils/MusicUtils)
**Returns**: number - seconds per beat
| Param | Type | Description |
| --- | --- | --- |
| bpm | number | tempo in beats per minute |
### utils/MusicUtils.freqToApproxMidiNr(frequency) ⇒ number
Maps any frequency (in Hz) to an approximate MIDI note number. Result can be
rounded to get to the closest MIDI note or used as is for a sound in between
two notes.
**Kind**: static method of [utils/MusicUtils](#module_utils/MusicUtils)
**Returns**: number - MIDI note number (not rounded)
| Param | Type | Description |
| --- | --- | --- |
| frequency | number | a frequency in Hz |
### utils/MusicUtils.midiToFrequency(midi) ⇒ number
Maps any MIDI number (can be in-between, like 69.5 for A4 + 50 cents) to its
frequency.
**Kind**: static method of [utils/MusicUtils](#module_utils/MusicUtils)
**Returns**: number - frequency in Hz
| Param | Type | Description |
| --- | --- | --- |
| midi | number | MIDI note number |
### utils/MusicUtils.chordToInteger(notes) ⇒ number
Turns a chord into an integer that uniquely describes the occuring chroma.
If the same chroma occurs twice this will not make a difference
(e.g. [C4, E4, G4, C5] will equal [C4, E4, G4])
How it works:
Chord has C, E, and G
x = 000010010001
G E C
**Kind**: static method of [utils/MusicUtils](#module_utils/MusicUtils)
**Returns**: number - an integer that uniquely identifies this chord's chroma
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
### utils/MusicUtils.chordIntegerJaccardIndex(chord1, chord2) ⇒ number
Takes two chord integer representations from chordToInteger() and computes
the Jaccard index
**Kind**: static method of [utils/MusicUtils](#module_utils/MusicUtils)
**Returns**: number - Jackard index, from 0 for different to 1 for identical
| Param | Type | Description |
| --- | --- | --- |
| chord1 | number | chord as integer representation |
| chord2 | number | chord as integer representation |
### utils/MusicUtils.noteDurationToNoteType(duration, bpm) ⇒ object
Estimates the note type (whole, quarter, ...) and number of dots for dotted
notes
**Kind**: static method of [utils/MusicUtils](#module_utils/MusicUtils)
**Returns**: object - note type and number of dots
e.g. { "dots": 0, "duration": 1, "type": 1 } for a whole note
e.g. { "dots": 1, "duration": 1.5, "type": 1 } for a dotted whole note
**Todo**
- [ ] test if corrrectly 'calibrated'
| Param | Type | Description |
| --- | --- | --- |
| duration | number | duration of a note |
| bpm | number | tempo of the piece in bpm |
### utils/MusicUtils.metronomeTrackFromTempoAndMeter(tempo, meter, duration) ⇒ Array.<object>
Creates a track of metronome ticks for a given tempo and meter.
**Kind**: static method of [utils/MusicUtils](#module_utils/MusicUtils)
**Returns**: Array.<object> - metronome track with {time: number, accent: boolean}
| Param | Type | Description |
| --- | --- | --- |
| tempo | number | tempo in bpm, e.g. 120 |
| meter | Array.<number> | e.g. [4, 4] |
| duration | number | duration of the resulting track in seconds |
### utils/MusicUtils.metronomeTrackFromMusicPiece(musicPiece, [tempoFactor]) ⇒ Array.<object>
Creates a track of metronome ticks for a given music piece.
**Kind**: static method of [utils/MusicUtils](#module_utils/MusicUtils)
**Returns**: Array.<object> - metronome track with {time: number, accent: boolean}
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| musicPiece | [MusicPiece](#MusicPiece) | | music piece |
| [tempoFactor] | number | 1 | rescale the tempo of the metronome, e.g. 2 for twice the speed |
## utils/NoteColorUtils
* [utils/NoteColorUtils](#module_utils/NoteColorUtils)
* [.noteColormap](#module_utils/NoteColorUtils.noteColormap) : Array.<string>
* [.noteColormapAccessible](#module_utils/NoteColorUtils.noteColormapAccessible) : Array.<string>
* [.noteColormapAccessible2](#module_utils/NoteColorUtils.noteColormapAccessible2) : Array.<string>
* [.newton](#module_utils/NoteColorUtils.newton) : Array.<string>
* [.castel](#module_utils/NoteColorUtils.castel) : Array.<string>
* [.field](#module_utils/NoteColorUtils.field) : Array.<string>
* [.jameson](#module_utils/NoteColorUtils.jameson) : Array.<string>
* [.seemann](#module_utils/NoteColorUtils.seemann) : Array.<string>
* [.rimington](#module_utils/NoteColorUtils.rimington) : Array.<string>
* [.bishop](#module_utils/NoteColorUtils.bishop) : Array.<string>
* [.helmholtz](#module_utils/NoteColorUtils.helmholtz) : Array.<string>
* [.scriabin](#module_utils/NoteColorUtils.scriabin) : Array.<string>
* [.klein](#module_utils/NoteColorUtils.klein) : Array.<string>
* [.aeppli](#module_utils/NoteColorUtils.aeppli) : Array.<string>
* [.belmont](#module_utils/NoteColorUtils.belmont) : Array.<string>
* [.zieverink](#module_utils/NoteColorUtils.zieverink) : Array.<string>
* [.colorInterpolator](#module_utils/NoteColorUtils.colorInterpolator) : function
* [.noteColormapGradientArray](#module_utils/NoteColorUtils.noteColormapGradientArray) : Array.<string>
* [.noteColorFromPitch(pitch, colormap)](#module_utils/NoteColorUtils.noteColorFromPitch) ⇒ string
### utils/NoteColorUtils.noteColormap : Array.<string>
Maps each note to a color
Colors from https://www.svpwiki.com/music+note+or+sound+colors
Order is C, C#, ... B
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.noteColormapAccessible : Array.<string>
Colorblind save colors from
Malandrino et al. - Visualization and Music Harmony: Design, Implementation,
and Evaluation https://ieeexplore.ieee.org/abstract/document/8564210
Order is C, C#, ... B
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.noteColormapAccessible2 : Array.<string>
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.newton : Array.<string>
Note colors by Isaac Newton, 1704 (shaprs were not assiged a color)
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.castel : Array.<string>
Note colors by Louis Betrand Castel, 1734
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.field : Array.<string>
Note colors by George Field, 1816 (shaprs were not assiged a color)
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.jameson : Array.<string>
Note colors by D.D. Jameson, 1844
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.seemann : Array.<string>
Note colors by Theodor Seemann, 1881
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.rimington : Array.<string>
Note colors by A. Wallace Rimington, 1893
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.bishop : Array.<string>
Note colors by Bainbridge Bishop, 1893
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.helmholtz : Array.<string>
Note colors by H. von Helmholtz, 1910
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.scriabin : Array.<string>
Note colors by Alexander Scriabin, 1911
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.klein : Array.<string>
Note colors by Adrian Bernard Klein, 1930
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.aeppli : Array.<string>
Note colors by August Aeppli, 1940 (C#, D#, F, G# were not assigned a color)
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.belmont : Array.<string>
Note colors by I.J. Belmont, 1944
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.zieverink : Array.<string>
Note colors by Steve Zieverink, 2004
From Schmidt, Kathryn L. (2019): Meaningful Music Visualizations. Purdue University Graduate School. Thesis.https://doi.org/10.25394/PGS.7498700.v1 https://hammer.purdue.edu/articles/thesis/Meaningful_Music_Visualizations/7498700/1/files/13893941.pdf page 13
Original: Collopy, F. (2004, October 19). Color scales? Retrieved from http://rhythmiclight.com/archives/ideas/colorscales.html
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.colorInterpolator : function
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.noteColormapGradientArray : Array.<string>
Gradient color map from black to steelblue
**Kind**: static constant of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
### utils/NoteColorUtils.noteColorFromPitch(pitch, colormap) ⇒ string
Returns the note color depending on the given pitch.
(Simplifies note color lookup by looking up the color for pitch%12.)
**Kind**: static method of [utils/NoteColorUtils](#module_utils/NoteColorUtils)
**Returns**: string - color code
| Param | Type | Description |
| --- | --- | --- |
| pitch | number | MIDI pitch in [0, 127] |
| colormap | string | one of 'default', 'accessible', 'gradient' |
## utils/RecordingsUtils
* [utils/RecordingsUtils](#module_utils/RecordingsUtils)
* [.filterRecordingNoise(recording, velocityThreshold, durationThreshold)](#module_utils/RecordingsUtils.filterRecordingNoise) ⇒ [Recording](#Recording)
* [.clipRecordingsPitchesToGtRange(recordings, groundTruth)](#module_utils/RecordingsUtils.clipRecordingsPitchesToGtRange) ⇒ [Array.<Recording>](#Recording)
* [.clipRecordingsPitchesToGtFretboardRange(recordings, groundTruth, [mode])](#module_utils/RecordingsUtils.clipRecordingsPitchesToGtFretboardRange) ⇒ [Array.<Recording>](#Recording)
* [.alignNotesToBpm(notes, bpm, timeDivision)](#module_utils/RecordingsUtils.alignNotesToBpm) ⇒ [Array.<Note>](#Note)
* [.recordingsHeatmap(recNotes, nRecs, binSize, attribute)](#module_utils/RecordingsUtils.recordingsHeatmap) ⇒ Map
* [.averageRecordings(heatmapByPitch, binSize, threshold)](#module_utils/RecordingsUtils.averageRecordings) ⇒ [Array.<Note>](#Note)
* [.averageRecordings2(recNotes, bandwidth, ticksPerSecond, threshold)](#module_utils/RecordingsUtils.averageRecordings2) ⇒ [Array.<Note>](#Note)
* [.differenceMap(gtNotes, recNotes, binSize)](#module_utils/RecordingsUtils.differenceMap) ⇒ Map
* [.differenceMapErrorAreas(differenceMap)](#module_utils/RecordingsUtils.differenceMapErrorAreas) ⇒ object
### utils/RecordingsUtils.filterRecordingNoise(recording, velocityThreshold, durationThreshold) ⇒ [Recording](#Recording)
Filters notes of a recording to remove noise from the MIDI device or pickup
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: [Recording](#Recording) - clone of the recording with filtered notes
**Todo**
- [ ] detect gaps and fill them
| Param | Type | Description |
| --- | --- | --- |
| recording | [Recording](#Recording) | a recording |
| velocityThreshold | number | notes with velocity < velocityThreshold are removed |
| durationThreshold | number | notes with duration < velocityThreshold are removed (value in seconds) |
### utils/RecordingsUtils.clipRecordingsPitchesToGtRange(recordings, groundTruth) ⇒ [Array.<Recording>](#Recording)
Removes notes from a recordings which are outside the range of the ground
truth and therefore likely noise.
Looks up the pitch range from the track of the GT that the recording was made
for.
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: [Array.<Recording>](#Recording) - filtered recordings
| Param | Type | Description |
| --- | --- | --- |
| recordings | [Array.<Recording>](#Recording) | recordings |
| groundTruth | Array.<Array.<Note>> | ground truth |
### utils/RecordingsUtils.clipRecordingsPitchesToGtFretboardRange(recordings, groundTruth, [mode]) ⇒ [Array.<Recording>](#Recording)
Removes notes from a recordings which are outside the fretboard range of the
ground truth and therefore likely noise.
Looks up the fretboard position range from the track of the GT that the
recording was made for.
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: [Array.<Recording>](#Recording) - filtered recordings
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| recordings | [Array.<Recording>](#Recording) | | recordings |
| groundTruth | Array.<Array.<Note>> | | ground truth |
| [mode] | 'exact' \| 'area' | exact | mode for which fretboard positions to include: exact will only keep notes that have positions that occur in the GT, area will get a rectangular area of the fretboard that contains all GT positions and fill filter on that. |
### utils/RecordingsUtils.alignNotesToBpm(notes, bpm, timeDivision) ⇒ [Array.<Note>](#Note)
Aligns notes to a rhythmic pattern
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: [Array.<Note>](#Note) - aligned notes
**Todo**
- [ ] not used
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| bpm | number | e.g. 120 for tempo 120 |
| timeDivision | number | e.g. 16 for 16th note steps |
### utils/RecordingsUtils.recordingsHeatmap(recNotes, nRecs, binSize, attribute) ⇒ Map
Calculates a heatmap either pitch- or channel-wise.
Pitch-time heatmap:
Calculates a heatmap of multiple recordings, to see the note density in the
pitch-time-space.
Channel-time heatmap:
Calculates a heatmap of multiple recordings, to see the note density in the
channel-time-space. Channel could be a guitar string or left and right hand
for example.
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: Map - pitch->heatmap; heatmap is number[] for all time slices
| Param | Type | Description |
| --- | --- | --- |
| recNotes | [Array.<Note>](#Note) | recordings |
| nRecs | number | number of recordings |
| binSize | number | time bin size in milliseconds |
| attribute | string | 'pitch' | 'channel' |
### utils/RecordingsUtils.averageRecordings(heatmapByPitch, binSize, threshold) ⇒ [Array.<Note>](#Note)
'Averages' multiple recordings of the same piece to get an approximation of
the ground truth.
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: [Array.<Note>](#Note) - approximated ground truth notes
**Todo**
- [ ] use velocity?
| Param | Type | Description |
| --- | --- | --- |
| heatmapByPitch | Map | haetmap from recordingsHeatmap() |
| binSize | number | size of time bins in milliseconds |
| threshold | number | note is regarded as true when this ratio of recordings has a note there |
### utils/RecordingsUtils.averageRecordings2(recNotes, bandwidth, ticksPerSecond, threshold) ⇒ [Array.<Note>](#Note)
Extracts a probable ground truth from multiple recordings. Uses one KDE for
each note starts and ends, detects maxima in the KDE and thresholds them.
Then uses alternating start end end candidates to create notes.
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: [Array.<Note>](#Note) - new notes
| Param | Type | Description |
| --- | --- | --- |
| recNotes | [Array.<Note>](#Note) | recordings notes |
| bandwidth | number | kernel bandwidth |
| ticksPerSecond | number | number of ticks per second |
| threshold | number | threshold |
### utils/RecordingsUtils.differenceMap(gtNotes, recNotes, binSize) ⇒ Map
Returns a Map: pitch->differenceMap, differenceMap is an Array with time bins
and each bin is either
0 (none, neither GT nor rec have a note here)
1 (missing, only GT has a note here)
2 (additional, only rec has a note here)
3 (both, both have a note here)
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: Map - pitch->differenceMap; differenceMap is number[] for all time slices
**Todo**
- [ ] move to comparison
| Param | Type | Description |
| --- | --- | --- |
| gtNotes | [Array.<Note>](#Note) | ground truth notes |
| recNotes | [Array.<Note>](#Note) | recrodings notes |
| binSize | number | size of a time bin in milliseconds |
**Example**
```js
const diffMap = differenceMap(gtNotes, recNotes, 10);
```
### utils/RecordingsUtils.differenceMapErrorAreas(differenceMap) ⇒ object
Computes the 'area' of error from a differenceMap normalized by total area.
The area is simply the number of bins with each value, total area is max.
number of bins in all pitches * the number of pitches.
**Kind**: static method of [utils/RecordingsUtils](#module_utils/RecordingsUtils)
**Returns**: object - {missing, additional, correct} area ratios
**Todo**
- [ ] move to comparison
- [ ] not used or tested yet
- [ ] add threshold for small errors (i.e. ignore area left and right of notes' start and end (masking?)))
| Param | Type | Description |
| --- | --- | --- |
| differenceMap | Map | differenceMap from differenceMap() |
**Example**
```js
const diffMap = differenceMap(gtNotes, recNotes, 10);
const diffMapErrors = differenceMapErrorAreas(diffMap);
const {missing, additional, correct} = diffMapErrors;
```
## utils/StatisticsUtils
* [utils/StatisticsUtils](#module_utils/StatisticsUtils)
* [.pearsonCorrelation(x, y)](#module_utils/StatisticsUtils.pearsonCorrelation) ⇒ number
* [.confidenceInterval(values)](#module_utils/StatisticsUtils.confidenceInterval) ⇒ object
* [.getBoxplotCharacteristics(values)](#module_utils/StatisticsUtils.getBoxplotCharacteristics) ⇒ object
* [.kernelDensityEstimator(kernel, X)](#module_utils/StatisticsUtils.kernelDensityEstimator) ⇒ function
* [~estimator(V)](#module_utils/StatisticsUtils.kernelDensityEstimator..estimator) ⇒ Array.<Array.<number>>
* [.kernelEpanechnikov(k)](#module_utils/StatisticsUtils.kernelEpanechnikov) ⇒ function
* [~epKernel(v)](#module_utils/StatisticsUtils.kernelEpanechnikov..epKernel) ⇒ number
* [.kernelGauss(k)](#module_utils/StatisticsUtils.kernelGauss) ⇒ function
* [~gaKernel(v)](#module_utils/StatisticsUtils.kernelGauss..gaKernel) ⇒ number
### utils/StatisticsUtils.pearsonCorrelation(x, y) ⇒ number
Computes the Pearson correlation
**Kind**: static method of [utils/StatisticsUtils](#module_utils/StatisticsUtils)
**Returns**: number - correlation
**Throws**:
- 'Invalid data, must be two arrays with same length' for invalid
arguments
- 'Invalid data, length must be >= 2' for invalid arguments
**See**: https://gist.github.com/matt-west/6500993#gistcomment-3718526
| Param | Type | Description |
| --- | --- | --- |
| x | Array.<number> | an array of numbers |
| y | Array.<number> | an array of numbers |
### utils/StatisticsUtils.confidenceInterval(values) ⇒ object
Calculates a 95% confidence interval
**Kind**: static method of [utils/StatisticsUtils](#module_utils/StatisticsUtils)
**Returns**: object - {mean, low, high}
**See**: https://www.alchemer.com/resources/blog/how-to-calculate-confidence-intervals/
| Param | Type | Description |
| --- | --- | --- |
| values | Array.<numnber> | values |
### utils/StatisticsUtils.getBoxplotCharacteristics(values) ⇒ object
Given an array of numbers, computes the proportions of a boxplot.
**Kind**: static method of [utils/StatisticsUtils](#module_utils/StatisticsUtils)
**Returns**: object - { q1, q2, q3, r0, r1 }
| Param | Type | Description |
| --- | --- | --- |
| values | Array.<number> | values |
### utils/StatisticsUtils.kernelDensityEstimator(kernel, X) ⇒ function
Returns a kernel desity estimator function.
**Kind**: static method of [utils/StatisticsUtils](#module_utils/StatisticsUtils)
**Returns**: function - kernel density estimator
**See**: https://www.d3-graph-gallery.com/graph/violin_basicDens.html
| Param | Type | Description |
| --- | --- | --- |
| kernel | function | kernel function |
| X | Array.<number> | domain |
**Example**
```js
// With x being a d3.scaleLinear() scale
const kde = kernelDensityEstimator(kernelEpanechnikov(0.2), x.ticks(50));
const estimate = kde(data);
```
#### kernelDensityEstimator~estimator(V) ⇒ Array.<Array.<number>>
Kernel desity estimator
For each value of X it computes the estimated density of the data values
in V. The result has the form [ [x1, est1], [x2, est2], ... ]
**Kind**: inner method of [kernelDensityEstimator](#module_utils/StatisticsUtils.kernelDensityEstimator)
**Returns**: Array.<Array.<number>> - estimates for points of X
| Param | Type | Description |
| --- | --- | --- |
| V | Array.<number> | values |
### utils/StatisticsUtils.kernelEpanechnikov(k) ⇒ function
Epanechnikov kernel
**Kind**: static method of [utils/StatisticsUtils](#module_utils/StatisticsUtils)
**Returns**: function - kernel function with curried k
| Param | Type | Description |
| --- | --- | --- |
| k | number | kernel size |
#### kernelEpanechnikov~epKernel(v) ⇒ number
Epanechnokov kernel function
**Kind**: inner method of [kernelEpanechnikov](#module_utils/StatisticsUtils.kernelEpanechnikov)
**Returns**: number - result
| Param | Type | Description |
| --- | --- | --- |
| v | number | value |
### utils/StatisticsUtils.kernelGauss(k) ⇒ function
Gauss kernel
**Kind**: static method of [utils/StatisticsUtils](#module_utils/StatisticsUtils)
**Returns**: function - kernel function with curried k
| Param | Type | Description |
| --- | --- | --- |
| k | number | kernel size |
#### kernelGauss~gaKernel(v) ⇒ number
Gaussian kernel function
**Kind**: inner method of [kernelGauss](#module_utils/StatisticsUtils.kernelGauss)
**Returns**: number - result
| Param | Type | Description |
| --- | --- | --- |
| v | number | value |
## utils/WebMidiUtils
### utils/WebMidiUtils.pingMidiDevice(deviceName, howOften)
Allows to ping a MIDI device that loops back to measure latency.
The tool loopMIDI does exactly this:
**Kind**: static method of [utils/WebMidiUtils](#module_utils/WebMidiUtils)
**See**: https://www.tobias-erichsen.de/software/loopmidi.html.
| Param | Type | Description |
| --- | --- | --- |
| deviceName | string | name of the MIDI device |
| howOften | number | how many times to ping the device |
**Example**
```js
pingMidiDevice('loopMIDI Port', 10);
```
## GuitarNote ⇐ [Note](#Note)
Guitar note class that reflects MIDI properties but has
absolute start and end times in seconds and
information on how to play it.
**Kind**: global class
**Extends**: [Note](#Note)
* [GuitarNote](#GuitarNote) ⇐ [Note](#Note)
* [new GuitarNote(pitch, start, velocity, channel, end, string, fret)](#new_GuitarNote_new)
* _instance_
* [.toNote()](#GuitarNote+toNote) ⇒ [Note](#Note)
* [.clone()](#GuitarNote+clone) ⇒ [GuitarNote](#GuitarNote)
* [.equals(otherNote)](#GuitarNote+equals) ⇒ boolean
* [.toString(short)](#GuitarNote+toString) ⇒ string
* [.getDuration()](#Note+getDuration) ⇒ number
* [.getName()](#Note+getName) ⇒ string
* [.getLetter()](#Note+getLetter) ⇒ string
* [.getOctave()](#Note+getOctave) ⇒ number
* [.shiftTime(addedSeconds)](#Note+shiftTime) ⇒ [Note](#Note)
* [.scaleTime(factor)](#Note+scaleTime) ⇒ [Note](#Note)
* [.overlapsInTime(otherNote)](#Note+overlapsInTime) ⇒ boolean
* [.overlapInSeconds(otherNote)](#Note+overlapInSeconds) ⇒ number
* _static_
* [.from(object)](#GuitarNote.from) ⇒ [GuitarNote](#GuitarNote)
* [.fromNote(note, string, fret)](#GuitarNote.fromNote) ⇒ [GuitarNote](#GuitarNote)
### new GuitarNote(pitch, start, velocity, channel, end, string, fret)
Creates a new Note
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| pitch | number | 0 | pitch |
| start | number | 0 | start time in seconds |
| velocity | number | 127 | velocity |
| channel | number | 0 | MIDI channel |
| end | number | number | number | Note](#Note)
Simplifies the GuitarNote to a Note
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Returns**: [Note](#Note) - note
### guitarNote.clone() ⇒ [GuitarNote](#GuitarNote)
Returns a copy of the Note object
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [clone](#Note+clone)
**Returns**: [GuitarNote](#GuitarNote) - new note
### guitarNote.equals(otherNote) ⇒ boolean
Returns true if this note and otherNote have equal attributes.
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [equals](#Note+equals)
**Returns**: boolean - true if equal
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [GuitarNote](#GuitarNote) | another GuitarNote |
### guitarNote.toString(short) ⇒ string
Human-readable string representation of this GuitarNote
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [toString](#Note+toString)
**Returns**: string - string representation
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| short | boolean | false | if true, attribute names will be shortened |
### guitarNote.getDuration() ⇒ number
Returns the duration of this note in seconds
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [getDuration](#Note+getDuration)
**Returns**: number - note duration
### guitarNote.getName() ⇒ string
Returns the note's name and octave, e.g. 'C#3'
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [getName](#Note+getName)
**Returns**: string - note name as string
### guitarNote.getLetter() ⇒ string
Returns the note's name WITHOUT the octave, e.g. 'C#'
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [getLetter](#Note+getLetter)
**Returns**: string - note name as string
### guitarNote.getOctave() ⇒ number
Returns the note's octave
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [getOctave](#Note+getOctave)
**Returns**: number - the note's octave
### guitarNote.shiftTime(addedSeconds) ⇒ [Note](#Note)
Returns a new Note where start and end are multiplied by factor
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [shiftTime](#Note+shiftTime)
**Returns**: [Note](#Note) - new note
| Param | Type | Description |
| --- | --- | --- |
| addedSeconds | number | seconds to be added to start and end |
### guitarNote.scaleTime(factor) ⇒ [Note](#Note)
Returns a new Note where start and end are multiplied by factor
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [scaleTime](#Note+scaleTime)
**Returns**: [Note](#Note) - new note
| Param | Type | Description |
| --- | --- | --- |
| factor | number | factor to scale start and end with |
### guitarNote.overlapsInTime(otherNote) ⇒ boolean
Returns true, if this Note and otherNote overlap in time.
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [overlapsInTime](#Note+overlapsInTime)
**Returns**: boolean - true if they overlap
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [Note](#Note) | another Note |
### guitarNote.overlapInSeconds(otherNote) ⇒ number
Returns the amount of seconds this Note and otherNote overlap in time.
**Kind**: instance method of [GuitarNote](#GuitarNote)
**Overrides**: [overlapInSeconds](#Note+overlapInSeconds)
**Returns**: number - seconds of overlap
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [Note](#Note) | another Note |
### GuitarNote.from(object) ⇒ [GuitarNote](#GuitarNote)
Creates a GuitarNote object from an object via destructuring
**Kind**: static method of [GuitarNote](#GuitarNote)
**Returns**: [GuitarNote](#GuitarNote) - new note
**Throws**:
- Error when pitch is invalid
| Param | Type | Description |
| --- | --- | --- |
| object | object | object with at least {pitch} { pitch: number|string e.g. 12 or C#4 start: number start time in seconds end: number end time in seconds velocity: number MIDI velocity channel: number MIDI channel string: number guitar string fret: number guitar fret } |
### GuitarNote.fromNote(note, string, fret) ⇒ [GuitarNote](#GuitarNote)
Converts a Note to a GuitarNote
**Kind**: static method of [GuitarNote](#GuitarNote)
**Returns**: [GuitarNote](#GuitarNote) - guitar note
| Param | Type | Description |
| --- | --- | --- |
| note | [Note](#Note) | note |
| string | number | string |
| fret | number | fret |
## HarmonicaNote ⇐ [Note](#Note)
Harmonica note class that reflects MIDI properties but has
absolute start and end times in seconds and
information on how to play it.
**Kind**: global class
**Extends**: [Note](#Note)
* [HarmonicaNote](#HarmonicaNote) ⇐ [Note](#Note)
* [new HarmonicaNote(pitch, start, velocity, channel, end, hole, instruction)](#new_HarmonicaNote_new)
* _instance_
* [.toNote()](#HarmonicaNote+toNote) ⇒ [Note](#Note)
* [.clone()](#HarmonicaNote+clone) ⇒ [GuitarNote](#GuitarNote)
* [.equals(otherNote)](#HarmonicaNote+equals) ⇒ boolean
* [.toString(short)](#HarmonicaNote+toString) ⇒ string
* [.getDuration()](#Note+getDuration) ⇒ number
* [.getName()](#Note+getName) ⇒ string
* [.getLetter()](#Note+getLetter) ⇒ string
* [.getOctave()](#Note+getOctave) ⇒ number
* [.shiftTime(addedSeconds)](#Note+shiftTime) ⇒ [Note](#Note)
* [.scaleTime(factor)](#Note+scaleTime) ⇒ [Note](#Note)
* [.overlapsInTime(otherNote)](#Note+overlapsInTime) ⇒ boolean
* [.overlapInSeconds(otherNote)](#Note+overlapInSeconds) ⇒ number
* _static_
* [.from(object)](#HarmonicaNote.from) ⇒ [HarmonicaNote](#HarmonicaNote)
* [.fromNote(note, hole, instruction)](#HarmonicaNote.fromNote) ⇒ [HarmonicaNote](#HarmonicaNote)
### new HarmonicaNote(pitch, start, velocity, channel, end, hole, instruction)
Creates a new Note
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| pitch | number | 0 | pitch |
| start | number | 0 | start time in seconds |
| velocity | number | 127 | velocity |
| channel | number | 0 | MIDI channel |
| end | number | number | 'blow' \| 'draw' \| 'bend' \| 'overblow' | Note](#Note)
Simplifies the HarmonicaNote to a Note
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Returns**: [Note](#Note) - note
### harmonicaNote.clone() ⇒ [GuitarNote](#GuitarNote)
Returns a copy of the Note object
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [clone](#Note+clone)
**Returns**: [GuitarNote](#GuitarNote) - new note
### harmonicaNote.equals(otherNote) ⇒ boolean
Returns true if this note and otherNote have equal attributes.
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [equals](#Note+equals)
**Returns**: boolean - true if equal
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [GuitarNote](#GuitarNote) | another GuitarNote |
### harmonicaNote.toString(short) ⇒ string
Human-readable string representation of this HarmonicaNote
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [toString](#Note+toString)
**Returns**: string - string representation
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| short | boolean | false | if true, attribute names will be shortened |
### harmonicaNote.getDuration() ⇒ number
Returns the duration of this note in seconds
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [getDuration](#Note+getDuration)
**Returns**: number - note duration
### harmonicaNote.getName() ⇒ string
Returns the note's name and octave, e.g. 'C#3'
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [getName](#Note+getName)
**Returns**: string - note name as string
### harmonicaNote.getLetter() ⇒ string
Returns the note's name WITHOUT the octave, e.g. 'C#'
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [getLetter](#Note+getLetter)
**Returns**: string - note name as string
### harmonicaNote.getOctave() ⇒ number
Returns the note's octave
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [getOctave](#Note+getOctave)
**Returns**: number - the note's octave
### harmonicaNote.shiftTime(addedSeconds) ⇒ [Note](#Note)
Returns a new Note where start and end are multiplied by factor
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [shiftTime](#Note+shiftTime)
**Returns**: [Note](#Note) - new note
| Param | Type | Description |
| --- | --- | --- |
| addedSeconds | number | seconds to be added to start and end |
### harmonicaNote.scaleTime(factor) ⇒ [Note](#Note)
Returns a new Note where start and end are multiplied by factor
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [scaleTime](#Note+scaleTime)
**Returns**: [Note](#Note) - new note
| Param | Type | Description |
| --- | --- | --- |
| factor | number | factor to scale start and end with |
### harmonicaNote.overlapsInTime(otherNote) ⇒ boolean
Returns true, if this Note and otherNote overlap in time.
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [overlapsInTime](#Note+overlapsInTime)
**Returns**: boolean - true if they overlap
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [Note](#Note) | another Note |
### harmonicaNote.overlapInSeconds(otherNote) ⇒ number
Returns the amount of seconds this Note and otherNote overlap in time.
**Kind**: instance method of [HarmonicaNote](#HarmonicaNote)
**Overrides**: [overlapInSeconds](#Note+overlapInSeconds)
**Returns**: number - seconds of overlap
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [Note](#Note) | another Note |
### HarmonicaNote.from(object) ⇒ [HarmonicaNote](#HarmonicaNote)
Creates a HarmonicaNote object from an object via destructuring
**Kind**: static method of [HarmonicaNote](#HarmonicaNote)
**Returns**: [HarmonicaNote](#HarmonicaNote) - new note
**Throws**:
- Error when pitch is invalid
| Param | Type | Description |
| --- | --- | --- |
| object | object | object with at least {pitch} { pitch: number|string e.g. 12 or C#4 start: number start time in seconds end: number end time in seconds velocity: number MIDI velocity channel: number MIDI channel hole: number harmonica hole instruction: string instruction, e.g., blow or draw } |
### HarmonicaNote.fromNote(note, hole, instruction) ⇒ [HarmonicaNote](#HarmonicaNote)
Converts a Note to a Harmonica
**Kind**: static method of [HarmonicaNote](#HarmonicaNote)
**Returns**: [HarmonicaNote](#HarmonicaNote) - harmonica note
| Param | Type | Description |
| --- | --- | --- |
| note | [Note](#Note) | note |
| hole | number | harmonica hole |
| instruction | 'blow' \| 'draw' \| 'bend' \| 'overblow' | instruction, e.g., blow or draw |
## ~~MusicPiece~~
***Deprecated***
Represents a parsed MIDI or MusicXML file in a uniform format.
**Kind**: global class
* ~~[MusicPiece](#MusicPiece)~~
* [new MusicPiece(name, tempos, timeSignatures, keySignatures, measureTimes, tracks, [xmlMeasureIndices])](#new_MusicPiece_new)
* _instance_
* [.toJson(pretty)](#MusicPiece+toJson) ⇒ string
* ~~[.getAllNotes(sortByTime)](#MusicPiece+getAllNotes) ⇒ [Array.<Note>](#Note)~~
* [.getNotesFromTracks(indices, sortByTime)](#MusicPiece+getNotesFromTracks) ⇒ [Array.<Note>](#Note)
* [.transpose(steps, tracks)](#MusicPiece+transpose) ⇒ [MusicPiece](#MusicPiece)
* _static_
* [.fromMidi(name, midiFile)](#MusicPiece.fromMidi) ⇒ [MusicPiece](#MusicPiece)
* [.fromMusicXml(name, xmlFile)](#MusicPiece.fromMusicXml) ⇒ [MusicPiece](#MusicPiece)
* [.fromJson(json)](#MusicPiece.fromJson) ⇒ [MusicPiece](#MusicPiece)
### new MusicPiece(name, tempos, timeSignatures, keySignatures, measureTimes, tracks, [xmlMeasureIndices])
**Throws**:
- 'No or invalid tracks given!' when invalid tracks are given
| Param | Type | Description |
| --- | --- | --- |
| name | string | name (e.g. file name or piece name) |
| tempos | [Array.<TempoDefinition>](#TempoDefinition) | tempos |
| timeSignatures | [Array.<TimeSignature>](#TimeSignature) | time signatures |
| keySignatures | [Array.<KeySignature>](#KeySignature) | key signatures |
| measureTimes | Array.<number> | time in seconds for each measure line |
| tracks | [Array.<Track>](#Track) | tracks |
| [xmlMeasureIndices] | Array.<number> | for each parsed measure, the index of the corresponding XML measure (only for MusicXML) |
### musicPiece.toJson(pretty) ⇒ string
Returns a JSON-serialized representation
**Kind**: instance method of [MusicPiece](#MusicPiece)
**Returns**: string - JSON as string
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| pretty | boolean | false | true for readable (prettified) JSON |
**Example**
```js
const jsonString = mp.toJson();
const recovered = MusicPiece.fromJson(jsonString);
```
### ~~musicPiece.getAllNotes(sortByTime) ⇒ [Array.<Note>](#Note)~~
***Deprecated***
Returns an array with all notes from all tracks.
**Kind**: instance method of [MusicPiece](#MusicPiece)
**Returns**: [Array.<Note>](#Note) - all notes of this piece
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| sortByTime | boolean | false | true: sort notes by time |
### musicPiece.getNotesFromTracks(indices, sortByTime) ⇒ [Array.<Note>](#Note)
Returns an array with notes from the specified tracks.
**Kind**: instance method of [MusicPiece](#MusicPiece)
**Returns**: [Array.<Note>](#Note) - Array with all notes from the specified tracks
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| indices | 'all' \| number \| Array.<number> | all | either 'all', a number, or an Array with numbers |
| sortByTime | boolean | false | true: sort notes by time (not needed for a single track) |
### musicPiece.transpose(steps, tracks) ⇒ [MusicPiece](#MusicPiece)
Transposes all or only the specified tracks by the specified number of
(semitone) steps.
Will return a new MusicPiece instance.
Note pitches will be clipped to [0, 127].
Will not change playing instructions such as string and fret.
**Kind**: instance method of [MusicPiece](#MusicPiece)
**Returns**: [MusicPiece](#MusicPiece) - a new, transposed MusicPiece
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| steps | number | 0 | number of semitones to transpose (can be negative) |
| tracks | 'all' \| number \| Array.<number> | all | tracks to transpose |
### MusicPiece.fromMidi(name, midiFile) ⇒ [MusicPiece](#MusicPiece)
Creates a MusicPiece object from a MIDI file binary
**Kind**: static method of [MusicPiece](#MusicPiece)
**Returns**: [MusicPiece](#MusicPiece) - new MusicPiece
**Throws**:
- 'No MIDI file content given' when MIDI file is undefined or null
| Param | Type | Description |
| --- | --- | --- |
| name | string | name |
| midiFile | ArrayBuffer | MIDI file |
**Example** *(In Node.js)*
```js
const file = path.join(directory, fileName);
const data = fs.readFileSync(file, 'base64');
const mp = MusicPiece.fromMidi(fileName, data);
```
**Example** *(In the browser)*
```js
const uintArray = new Uint8Array(midiBinary);
const MP = MusicPiece.fromMidi(filename, uintArray);
```
### MusicPiece.fromMusicXml(name, xmlFile) ⇒ [MusicPiece](#MusicPiece)
Creates a MusicPiece object from a MusicXML string
**Kind**: static method of [MusicPiece](#MusicPiece)
**Returns**: [MusicPiece](#MusicPiece) - new MusicPiece
**Throws**:
- 'No MusicXML file content given' when MusicXML file is
undefined or null
| Param | Type | Description |
| --- | --- | --- |
| name | string | name |
| xmlFile | string \| object | MusicXML file content as string or object If it is an object, it must behave like a DOM, e.g. provide methods such as .querySelectorAll() |
**Example**
```js
Parsing a MusicPiece in Node.js
const jsdom = require('jsdom');
const xmlFile = fs.readFileSync('My Song.musicxml');
const dom = new jsdom.JSDOM(xmlFile);
const xmlDocument = dom.window.document;
const mp = musicvislib.MusicPiece.fromMusicXml('My Song', xmlDocument);
```
### MusicPiece.fromJson(json) ⇒ [MusicPiece](#MusicPiece)
Allows to get a MusicPiece from JSON after doing JSON.stringify()
**Kind**: static method of [MusicPiece](#MusicPiece)
**Returns**: [MusicPiece](#MusicPiece) - new MusicPiece
| Param | Type | Description |
| --- | --- | --- |
| json | string \| object | JSON |
**Example**
```js
const jsonString = mp.toJson();
const recovered = MusicPiece.fromJson(jsonString);
```
## Note
Note class that reflects MIDI properties but has
absolute start and end times in seconds.
**Kind**: global class
* [Note](#Note)
* [new Note(pitch, start, velocity, channel, end)](#new_Note_new)
* _instance_
* [.clone()](#Note+clone) ⇒ [Note](#Note)
* [.getDuration()](#Note+getDuration) ⇒ number
* [.getName()](#Note+getName) ⇒ string
* [.getLetter()](#Note+getLetter) ⇒ string
* [.getOctave()](#Note+getOctave) ⇒ number
* [.shiftTime(addedSeconds)](#Note+shiftTime) ⇒ [Note](#Note)
* [.scaleTime(factor)](#Note+scaleTime) ⇒ [Note](#Note)
* [.overlapsInTime(otherNote)](#Note+overlapsInTime) ⇒ boolean
* [.overlapInSeconds(otherNote)](#Note+overlapInSeconds) ⇒ number
* [.equals(otherNote)](#Note+equals) ⇒ boolean
* [.toString(short)](#Note+toString) ⇒ string
* _static_
* [.from(object)](#Note.from) ⇒ [Note](#Note)
* [.startPitchComparator(a, b)](#Note.startPitchComparator) ⇒ number
### new Note(pitch, start, velocity, channel, end)
Creates a new Note. Note.from() is preferred over using the constructor.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| pitch | number | 0 | pitch |
| start | number | 0 | start time in seconds |
| velocity | number | 127 | velocity |
| channel | number | 0 | MIDI channel |
| end | number | Note](#Note)
Returns a copy of the Note object
**Kind**: instance method of [Note](#Note)
**Returns**: [Note](#Note) - new note
### note.getDuration() ⇒ number
Returns the duration of this note in seconds
**Kind**: instance method of [Note](#Note)
**Returns**: number - note duration
### note.getName() ⇒ string
Returns the note's name and octave, e.g. 'C#3'
**Kind**: instance method of [Note](#Note)
**Returns**: string - note name as string
### note.getLetter() ⇒ string
Returns the note's name WITHOUT the octave, e.g. 'C#'
**Kind**: instance method of [Note](#Note)
**Returns**: string - note name as string
### note.getOctave() ⇒ number
Returns the note's octave
**Kind**: instance method of [Note](#Note)
**Returns**: number - the note's octave
### note.shiftTime(addedSeconds) ⇒ [Note](#Note)
Returns a new Note where start and end are multiplied by factor
**Kind**: instance method of [Note](#Note)
**Returns**: [Note](#Note) - new note
| Param | Type | Description |
| --- | --- | --- |
| addedSeconds | number | seconds to be added to start and end |
### note.scaleTime(factor) ⇒ [Note](#Note)
Returns a new Note where start and end are multiplied by factor
**Kind**: instance method of [Note](#Note)
**Returns**: [Note](#Note) - new note
| Param | Type | Description |
| --- | --- | --- |
| factor | number | factor to scale start and end with |
### note.overlapsInTime(otherNote) ⇒ boolean
Returns true, if this Note and otherNote overlap in time.
**Kind**: instance method of [Note](#Note)
**Returns**: boolean - true if they overlap
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [Note](#Note) | another Note |
### note.overlapInSeconds(otherNote) ⇒ number
Returns the amount of seconds this Note and otherNote overlap in time.
**Kind**: instance method of [Note](#Note)
**Returns**: number - seconds of overlap
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [Note](#Note) | another Note |
### note.equals(otherNote) ⇒ boolean
Returns true if this note and otherNote have equal attributes.
**Kind**: instance method of [Note](#Note)
**Returns**: boolean - true if equal
| Param | Type | Description |
| --- | --- | --- |
| otherNote | [Note](#Note) | another Note |
### note.toString(short) ⇒ string
Human-readable string representation of this Note
**Kind**: instance method of [Note](#Note)
**Returns**: string - string representation
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| short | boolean | false | if true, attribute names will be shortened |
### Note.from(object) ⇒ [Note](#Note)
Creates a Note object from an object via destructuring.
Use either 'end' or 'duration', if both are specified, end will be used.
**Kind**: static method of [Note](#Note)
**Returns**: [Note](#Note) - new note
**Throws**:
- Error when pitch is invalid
| Param | Type | Description |
| --- | --- | --- |
| object | object | object with at least {pitch} |
| object.pitch | number \| string | e.G. 12 or C#4 |
| object.start | number | start time in seconds |
| object.end | number | end time in seconds |
| object.duration | number | duration in seconds |
| object.velocity | number | MIDI velocity |
| object.channel | number | MIDI channel |
**Example** *(Using end)*
```js
const n = Note.from({
pitch: 'C#4', // e.g. 12 or C#4
start: 0.5, // start time in seconds
end: 1.5, // end time in seconds
velocity: 127, // MIDI velocity
channel: 0, // MIDI channel
});
```
**Example** *(Using duration)*
```js
const n = Note.from({
pitch: 'C#4',
start: 0.5,
duration: 1.2,
});
```
### Note.startPitchComparator(a, b) ⇒ number
Allows to sort notes by time ascending, notes with equal start time will
be sorted by pitch ascending.
**Kind**: static method of [Note](#Note)
**Returns**: number - negative for smaller, positive for greater, 0 for euqal
| Param | Type | Description |
| --- | --- | --- |
| a | [Note](#Note) | a note to compare |
| b | [Note](#Note) | a note to compare |
## NoteArray
This class represents an array of note objects.
It can be used to simplify operations on a track.
**Kind**: global class
* [NoteArray](#NoteArray)
* [new NoteArray([notes], [reUseNotes])](#new_NoteArray_new)
* [.getNotes()](#NoteArray+getNotes) ⇒ [Array.<Note>](#Note)
* [.setNotes(notes)](#NoteArray+setNotes) ⇒ [NoteArray](#NoteArray)
* [.addNotes(notes, sort)](#NoteArray+addNotes) ⇒ [NoteArray](#NoteArray)
* [.concat(noteArray)](#NoteArray+concat) ⇒ [NoteArray](#NoteArray)
* [.append(noteArray, gap)](#NoteArray+append) ⇒ [NoteArray](#NoteArray)
* [.repeat(times)](#NoteArray+repeat) ⇒ [NoteArray](#NoteArray)
* [.length()](#NoteArray+length) ⇒ number
* [.getStartTime()](#NoteArray+getStartTime) ⇒ number
* [.getDuration()](#NoteArray+getDuration) ⇒ number
* [.scaleTime(factor)](#NoteArray+scaleTime) ⇒ [NoteArray](#NoteArray)
* [.shiftTime(addedSeconds)](#NoteArray+shiftTime) ⇒ [NoteArray](#NoteArray)
* [.shiftToStartAt(startTime)](#NoteArray+shiftToStartAt) ⇒ [NoteArray](#NoteArray)
* [.forEach(func)](#NoteArray+forEach) ⇒ [NoteArray](#NoteArray)
* [.sort(sortFunction)](#NoteArray+sort) ⇒ [NoteArray](#NoteArray)
* [.sortByTime()](#NoteArray+sortByTime) ⇒ [NoteArray](#NoteArray)
* [.map(mapFunction)](#NoteArray+map) ⇒ [NoteArray](#NoteArray)
* [.slice(start, end)](#NoteArray+slice) ⇒ [NoteArray](#NoteArray)
* [.sliceTime(startTime, endTime, [mode])](#NoteArray+sliceTime) ⇒ [NoteArray](#NoteArray)
* [.sliceAtTimes(times, mode, [reUseNotes])](#NoteArray+sliceAtTimes) ⇒ Array.<Array.<Note>>
* [.segmentAtGaps(gapDuration, mode)](#NoteArray+segmentAtGaps) ⇒ Array.<Array.<Note>>
* [.segmentAtIndices(indices)](#NoteArray+segmentAtIndices) ⇒ Array.<Array.<Note>>
* [.filter(filterFunction)](#NoteArray+filter) ⇒ [NoteArray](#NoteArray)
* [.filterPitches(pitches)](#NoteArray+filterPitches) ⇒ [NoteArray](#NoteArray)
* [.transpose(steps)](#NoteArray+transpose) ⇒ [NoteArray](#NoteArray)
* [.removeOctaves()](#NoteArray+removeOctaves) ⇒ [NoteArray](#NoteArray)
* [.reverse()](#NoteArray+reverse) ⇒ [NoteArray](#NoteArray)
* [.equals(otherNoteArray)](#NoteArray+equals) ⇒ boolean
* [.clone()](#NoteArray+clone) ⇒ [NoteArray](#NoteArray)
### new NoteArray([notes], [reUseNotes])
Creates a new NoteArray,
will make a copy of the passed array and cast all notes
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [notes] | [Array.<Note>](#Note) | [] | notes |
| [reUseNotes] | boolean | false | if true, will directly use the passed notes. This can be dangerous if you do not want them to change. |
**Example**
```js
const notes = [
// Some Note objects
];
const noteArr = new NoteArray(notes)
// Add more notes (all notes will be sorted by time by default after this)
.addNotes([])
// Scale all note's sart and end time to make a track slower or faster
.scaleTime(0.5)
// Do more ...
// This class also mirrors many functions from the Array class
.sort(sortFunction).filter(filterFunction).map(mapFunction).slice(0, 20)
// Get Note objects back in a simple Array
const transformedNotes = noteArr.getNotes();
// [Note, Note, Note, ...]
// Or use an iterator
for (const note of noteArr) {
console.log(note);
}
```
### noteArray.getNotes() ⇒ [Array.<Note>](#Note)
Returns a simple array with all Note objects.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [Array.<Note>](#Note) - array with Note objects
**Example** *(Getting notes as simple Note[])*
```js
const na = new NoteArray(someNotes);
const notes = na.getNotes();
```
**Example** *(Using an iterator instead)*
```js
const na = new NoteArray(someNotes);
for (const note of na) {
console.log(note);
}
// Or copy all Notes to an array with
const array = [...na];
```
### noteArray.setNotes(notes) ⇒ [NoteArray](#NoteArray)
Overwrite the NoteArray's notes with another Array of Notes
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
### noteArray.addNotes(notes, sort) ⇒ [NoteArray](#NoteArray)
Appends notes to this NoteArray
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| notes | [Array.<Note>](#Note) | | notes |
| sort | boolean | true | iff ture, sorts notes by start timeafter adding the new ones (default:true) |
### noteArray.concat(noteArray) ⇒ [NoteArray](#NoteArray)
Adds the notes from another NoteArray to this NoteArray
IMPORTANT: this does not change the notes or sort them!
Take a look at NoteArray.append() if you want to extend
a track at its end.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| noteArray | [NoteArray](#NoteArray) | another NoteArray |
### noteArray.append(noteArray, gap) ⇒ [NoteArray](#NoteArray)
Appends notes to the end of this NoteArray, after shifting them by its
duration. Set gap to something != 0 to create a gap or overlap.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| noteArray | [NoteArray](#NoteArray) | | another NoteArray |
| gap | number | 0 | in seconds between the two parts |
### noteArray.repeat(times) ⇒ [NoteArray](#NoteArray)
Repeats the notes of this array by concatenating a time-shifted copy
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - a new NoteArray with the repeated note sequence
| Param | Type | Description |
| --- | --- | --- |
| times | number | number of times to repeat it |
### noteArray.length() ⇒ number
Returns the number of Note objects in this NoteArray
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: number - note count
### noteArray.getStartTime() ⇒ number
Returns the start time of the earliest note in this NoteArray
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: number - start time
### noteArray.getDuration() ⇒ number
Returns the duration of this note array in seconds from 0 to the end of
the latest note.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: number - duration
### noteArray.scaleTime(factor) ⇒ [NoteArray](#NoteArray)
Scales the time of each note by factor
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| factor | number | factor |
### noteArray.shiftTime(addedSeconds) ⇒ [NoteArray](#NoteArray)
Adds the speicifed number of seconds to each note
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| addedSeconds | number | time to add in seconds |
### noteArray.shiftToStartAt(startTime) ⇒ [NoteArray](#NoteArray)
Moves all notes s.t. the first starts at NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| startTime | number | the new start time for the earliest note |
### noteArray.forEach(func) ⇒ [NoteArray](#NoteArray)
Similar to Array.forEach
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - this
| Param | Type | Description |
| --- | --- | --- |
| func | function | a function |
### noteArray.sort(sortFunction) ⇒ [NoteArray](#NoteArray)
Sorts the notes
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| sortFunction | function | sort function, e.g. (a, b)=>a.start-b.start |
### noteArray.sortByTime() ⇒ [NoteArray](#NoteArray)
Sorts the notes by start time
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
### noteArray.map(mapFunction) ⇒ [NoteArray](#NoteArray)
Maps the notes using some mapping function
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| mapFunction | function | mapping function with same signature as Array.map() |
### noteArray.slice(start, end) ⇒ [NoteArray](#NoteArray)
Slices the notes by index, like Array.slice()
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| start | number | start index |
| end | number | end index |
### noteArray.sliceTime(startTime, endTime, [mode]) ⇒ [NoteArray](#NoteArray)
Slices the notes by time.
The modes 'end' and 'contained' will remove all notes with end === null!
Notes will not be changed, e.g. start time will remain the same.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
**Throws**:
- 'Invalid slicing mode' When slicing mode is not one of the
above values
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| startTime | number | | start of the filter range in seconds |
| endTime | number | | end of the filter range in seconds (exclusive) |
| [mode] | string | "contained" | controls which note time to consider, one of: - start: note.start must be inside range - end: note.end must be inside range - contained: BOTH note.start and note.end must be inside range - touched: EITHER start or end (or both) must be inside range) - touched-included: like touched, but also includes notes where neither start nor end inside range, but range is completely inside the note (contained is default) |
### noteArray.sliceAtTimes(times, mode, [reUseNotes]) ⇒ Array.<Array.<Note>>
Slices this NoteArray into slices by the given times. Will not return
NoteArrays but simple Note[][], where each item contains all notes of one
time slice. Do not include 0, it will be assumed as first time to slice.
To make sure notes are not contained twice in different slices use the
mode 'start'.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: Array.<Array.<Note>> - time slices
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| times | Array.<number> | | points of time at which to slice (in seconds) |
| mode | string | | see NoteArray.sliceTime() |
| [reUseNotes] | boolean | false | if true, will not clone notes. This can be dangerous if you do not want them to change. |
**Example**
```js
// Slice into 1 second slices
const slices = noteArray.sliceAtTimes([1, 2, 3], 'start)
```
### noteArray.segmentAtGaps(gapDuration, mode) ⇒ Array.<Array.<Note>>
Segments the NoteArray into smaller ones at times where no note occurs
for a specified amount of time.
This method is useful for segmenting a recording session into separate
songs, riffs, licks, ...
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: Array.<Array.<Note>> - segments
| Param | Type | Description |
| --- | --- | --- |
| gapDuration | number | duration of seconds for a gap to be used as segmenting time |
| mode | 'start-start' \| 'end-start' | gaps can either be considered as the maximum time between two note's starts or the end of the first and the start of the second note |
### noteArray.segmentAtIndices(indices) ⇒ Array.<Array.<Note>>
Segments the NoteArray into Arrays of Notes at given indices
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: Array.<Array.<Note>> - segments
| Param | Type | Description |
| --- | --- | --- |
| indices | Array.<number> | indices |
**Example** *(Get notes in partions of 4)*
```js
const noteGroups = myNoteArray.segmentAtIndices([4, 8, 12, 16, 20]);
// noteGroups = [
// Array(4),
// Array(4),
// Array(4),
// ]
```
### noteArray.filter(filterFunction) ⇒ [NoteArray](#NoteArray)
Filters the NoteArray like you would filter via Array.filter().
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| filterFunction | function | filter function, same signature as Array.filter() |
**Example**
```js
// Only keep notes longer than 1 second
const filtered = noteArray.filter(note=>note.getDuration()>1);
```
### noteArray.filterPitches(pitches) ⇒ [NoteArray](#NoteArray)
Filters by pitch, keeping only pitches specified in NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| pitches | Array.<number> \| Set.<number> | array or Set of pitches to keep |
### noteArray.transpose(steps) ⇒ [NoteArray](#NoteArray)
Transposes each note by NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
| Param | Type | Description |
| --- | --- | --- |
| steps | number | number of semitones to transpose, can be negative |
### noteArray.removeOctaves() ⇒ [NoteArray](#NoteArray)
Will set the octave of all notes to -1.
This might cause two notes to exist at the same time and pitch!
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
### noteArray.reverse() ⇒ [NoteArray](#NoteArray)
Reverses the note array, such that it can be played backwards.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - itself
### noteArray.equals(otherNoteArray) ⇒ boolean
Returns true if this NoteArray and otherNoteArray have equal attributes.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: boolean - true if equal
| Param | Type | Description |
| --- | --- | --- |
| otherNoteArray | [NoteArray](#NoteArray) | another NoteArray |
### noteArray.clone() ⇒ [NoteArray](#NoteArray)
Deep clone, all contained notes are cloned as well.
**Kind**: instance method of [NoteArray](#NoteArray)
**Returns**: [NoteArray](#NoteArray) - clone
## PitchBend
Class that allows to represent pitch-bends from a MIDI file
**Kind**: global class
**Todo**
- [ ] NYI
- [ ] not used yet
- [ ] can we aggregated pitchbend events into one PitchBend?
needs amounts: number[]
aggregation ends when amount is 0 (for some time? otherwise vibrato will be multiple PB)
* [PitchBend](#PitchBend)
* [new PitchBend(start, amount, channel)](#new_PitchBend_new)
* [.from(object)](#PitchBend.from) ⇒ [PitchBend](#PitchBend)
### new PitchBend(start, amount, channel)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| start | number | 0 | start time in seconds |
| amount | number | 0 | bend amount |
| channel | number | 0 | MIDI channel |
### PitchBend.from(object) ⇒ [PitchBend](#PitchBend)
Creates a GuitarNote object from an object via destructuring
**Kind**: static method of [PitchBend](#PitchBend)
**Returns**: [PitchBend](#PitchBend) - new note
| Param | Type | Description |
| --- | --- | --- |
| object | object | object with at least {pitch} |
## PitchSequence
Stores a sequence of pitches and provides some methods to simplify and
manipulate it.
**Kind**: global class
**Todo**
- [ ] implement keepOnlyHighestConcurrentNotes
* [PitchSequence](#PitchSequence)
* [new PitchSequence(pitches)](#new_PitchSequence_new)
* _instance_
* [.getPitches()](#PitchSequence+getPitches) ⇒ Array.<number>
* [.length()](#PitchSequence+length) ⇒ number
* [.toCharString()](#PitchSequence+toCharString) ⇒ string
* [.toNoteNameString()](#PitchSequence+toNoteNameString) ⇒ string
* [.reverse()](#PitchSequence+reverse) ⇒ [PitchSequence](#PitchSequence)
* [.removeOctaves()](#PitchSequence+removeOctaves) ⇒ [PitchSequence](#PitchSequence)
* [.toIntervals()](#PitchSequence+toIntervals) ⇒ Array.<number>
* [.clone()](#PitchSequence+clone) ⇒ [PitchSequence](#PitchSequence)
* [.equals(otherPitchSequence)](#PitchSequence+equals) ⇒ boolean
* _static_
* [.fromNotes(notes)](#PitchSequence.fromNotes) ⇒ [PitchSequence](#PitchSequence)
* [.fromCharString(string)](#PitchSequence.fromCharString) ⇒ [PitchSequence](#PitchSequence)
### new PitchSequence(pitches)
| Param | Type | Description |
| --- | --- | --- |
| pitches | Array.<number> | pitches |
### pitchSequence.getPitches() ⇒ Array.<number>
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: Array.<number> - pitches
### pitchSequence.length() ⇒ number
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: number - number of pitches
### pitchSequence.toCharString() ⇒ string
Turns pitch sequence into a string by turning each pitch into a character
(based on Unicode index)
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: string - string representation of note pitches
### pitchSequence.toNoteNameString() ⇒ string
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: string - a string with the notes' names
### pitchSequence.reverse() ⇒ [PitchSequence](#PitchSequence)
Reverses the order of pitches in this PitchSequence
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: [PitchSequence](#PitchSequence) - this
### pitchSequence.removeOctaves() ⇒ [PitchSequence](#PitchSequence)
Takes a sequence of MIDI pitches and nomralizes them to be in [0, 11]
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: [PitchSequence](#PitchSequence) - this
### pitchSequence.toIntervals() ⇒ Array.<number>
Transforms note pitches to intervals, i.e. diffrences between to subsequent
notes: C, C#, C, D => 1, -1, 2
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: Array.<number> - intervals
### pitchSequence.clone() ⇒ [PitchSequence](#PitchSequence)
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: [PitchSequence](#PitchSequence) - clone
### pitchSequence.equals(otherPitchSequence) ⇒ boolean
Returns true if this NoteArray and otherNoteArray have equal attributes.
**Kind**: instance method of [PitchSequence](#PitchSequence)
**Returns**: boolean - true if equal
| Param | Type | Description |
| --- | --- | --- |
| otherPitchSequence | [NoteArray](#NoteArray) | another NoteArray |
### PitchSequence.fromNotes(notes) ⇒ [PitchSequence](#PitchSequence)
Creates a pitch sequence from an array of Notes
**Kind**: static method of [PitchSequence](#PitchSequence)
**Returns**: [PitchSequence](#PitchSequence) - pitch sequence
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
### PitchSequence.fromCharString(string) ⇒ [PitchSequence](#PitchSequence)
**Kind**: static method of [PitchSequence](#PitchSequence)
**Returns**: [PitchSequence](#PitchSequence) - pitch sequence
| Param | Type | Description |
| --- | --- | --- |
| string | string | a string of Unicode characters |
## Recording
Class for storing recorded notes alongside meta information.
**Kind**: global class
* [Recording](#Recording)
* [new Recording(name, date, notes, [speed], [selectedTrack], [timeSelection], [comment])](#new_Recording_new)
* _instance_
* [.clone()](#Recording+clone) ⇒ [Recording](#Recording)
* [.equals(otherRecording)](#Recording+equals) ⇒ boolean
* [.toSimpleObject()](#Recording+toSimpleObject) ⇒ object
* _static_
* [.from(object)](#Recording.from) ⇒ [Recording](#Recording)
### new Recording(name, date, notes, [speed], [selectedTrack], [timeSelection], [comment])
Creates a new Recording
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| name | string | | name if the song |
| date | Date | | date of the recording |
| notes | [Array.<Note>](#Note) | | array of Note objects |
| [speed] | number | 1 | relative speed compared to ground truth, e.g. 0.5 for half as fast |
| [selectedTrack] | number | 0 | track number of the ground truth to which this recording belongs |
| [timeSelection] | Array.<number> \| null | string | "''" | a free-text comment for the user to annotate the recording |
### recording.clone() ⇒ [Recording](#Recording)
Returns a copy of the Note object
**Kind**: instance method of [Recording](#Recording)
**Returns**: [Recording](#Recording) - new recording
### recording.equals(otherRecording) ⇒ boolean
Returns true if this Recording and otherRecording have equal attributes.
**Kind**: instance method of [Recording](#Recording)
**Returns**: boolean - true if equal
| Param | Type | Description |
| --- | --- | --- |
| otherRecording | [Recording](#Recording) | another Recording |
### recording.toSimpleObject() ⇒ object
Turns the recoring into a simple object with the same properties
**Kind**: instance method of [Recording](#Recording)
**Returns**: object - simple object representation of the recording
### Recording.from(object) ⇒ [Recording](#Recording)
Creates a Note object from an object via destructuring
**Kind**: static method of [Recording](#Recording)
**Returns**: [Recording](#Recording) - new note
**Throws**:
- Error when name, date, or notes are missing
| Param | Type | Description |
| --- | --- | --- |
| object | object | object with at least {name, date, notes, speed} |
## drumInstrumentMap : Map.<string, object>
Maps internal drum names to MusicXML instrument names and note display
**Kind**: global constant
## patterns : Map.<string, object>
Contains patterns for exercises, such as scales
**Kind**: global constant
## patterns : Map.<string, object>
Contains patterns for exercises, such as scales
TODO: find way to automatically compute patterns from scales, get scales from tonaljs
**Kind**: global constant
## noteErrorTypes : object
**Kind**: global constant
## chordErrorTypes : object
**Kind**: global constant
## priorityMatching(itemsA, itemsB, distanceFunction) ⇒ Map.<number, number>
Idea: Like in hierarchical clustering, take the most similar pair out of the
set of all possible pairs repeatedly, until one array of items is empty.
**Kind**: global function
**Returns**: Map.<number, number> - with the indices of the matched items
| Param | Type | Description |
| --- | --- | --- |
| itemsA | Array.<T1> | an array with items |
| itemsB | Array.<T2> | an array with items |
| distanceFunction | function | distance function for two items, must be 0 for equal items and symmetric |
## errorFromPriorityMatching(gtNotes, recNotes, distanceFunction) ⇒ Map.<Note, number>
First matches GT to rec notes via priorityMatching, then computes the error
for each GT note that has been matched using the same distance function.
The Map will be undefined for GT notes that have not been matched, they can
be considered missing in the recording.
**Kind**: global function
**Returns**: Map.<Note, number> - a Map from GT note to its error
| Param | Type | Description |
| --- | --- | --- |
| gtNotes | [Array.<Note>](#Note) | ground truth notes |
| recNotes | [Array.<Note>](#Note) | recorded notes |
| distanceFunction | function | distance function, taking two notes and returning the 'distance', i.e. how different they are. See balancedNoteDistance as example. |
## balancedNoteDistance(a, b) ⇒ number
Computes a distance (inverse similarity) of two notes, considering pitch,
chroma, start, duration, and channel.
**Kind**: global function
**Returns**: number - distance
| Param | Type | Description |
| --- | --- | --- |
| a | [Note](#Note) | a Note |
| b | [Note](#Note) | a Note |
## getMatrixMinPosition(matrix) ⇒ Array.<number>
Returns the row and colum indices of the minimum value of the given matrix
**Kind**: global function
**Returns**: Array.<number> - [rowIndex, columIndex] of the minimum value
| Param | Type | Description |
| --- | --- | --- |
| matrix | Array.<Array.<number>> | matrix |
## generatePattern(patternType, [repeat]) ⇒ Array.<Array.<number>>
Takes a baseline pattern and moves it to the correct position on the fretboard
**Kind**: global function
**Returns**: Array.<Array.<number>> - array of [string, fret] positions
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| patternType | string | | pattern type |
| [repeat] | number | 1 | number of repeats |
## generateXml(name, tempo, timeSig, drumHits) ⇒ string
Generates MusicXML text from a pattern
**Kind**: global function
**Returns**: string - MusicXML string
| Param | Type | Description |
| --- | --- | --- |
| name | string | name |
| tempo | number | tempo in bpm |
| timeSig | string | time signature e.g. 4/4 |
| drumHits | Array.<Array.<number>> | the output of generatePattern |
## generatePattern(patternType, rootNote, [repeat], [alternate]) ⇒ Array.<Array.<number>>
Takes a baseline pattern and moves it to the correct position on the fretboard
**Kind**: global function
**Returns**: Array.<Array.<number>> - array of [string, fret] positions
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| patternType | string | | pattern type |
| rootNote | string | | root note |
| [repeat] | number | 1 | number of repetitions |
| [alternate] | boolena | false | reverse notes every second repetition |
## generateXml(name, tempo, timeSig, positions) ⇒ string
Generates MusicXML text from a pattern
**Kind**: global function
**Returns**: string - MusicXML string
| Param | Type | Description |
| --- | --- | --- |
| name | string | name |
| tempo | number | tempo in bpm |
| timeSig | string | time signature e.g. 4/4 |
| positions | Array.<Array.<number>> | the output of generatePattern |
## generatePattern(patternType, [rootNote], [scaleType], [repeat], [alternate]) ⇒ Array.<Array.<number>>
Takes a baseline pattern and moves it to the correct position on the fretboard
**Kind**: global function
**Returns**: Array.<Array.<number>> - array of [string, fret] positions
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| patternType | string | | pattern type |
| [rootNote] | string | "C" | root note |
| [scaleType] | string | "major" | see tonaljs scale types |
| [repeat] | number | 1 | number of repetitions |
| [alternate] | boolean | false | reverse notes every second repetition |
## repeatPattern(nRepetitions, pattern, alternate) ⇒ Array
Repeats a pattern with or without alternating direction
**Kind**: global function
**Returns**: Array - repeated pattern
| Param | Type | Description |
| --- | --- | --- |
| nRepetitions | number | number of repetitions |
| pattern | Array | pattern |
| alternate | boolean | alternate direction? |
## generateXml(name, tempo, timeSig, notes) ⇒ string
Generates MusicXML text from a pattern
**Kind**: global function
**Returns**: string - MusicXML string
| Param | Type | Description |
| --- | --- | --- |
| name | string | name |
| tempo | number | tempo in bpm |
| timeSig | string | time signature e.g. 4/4 |
| notes | Object | the output of generatePattern |
## getStartTimeErrorPerGtNote(gtNotes, recNotes) ⇒ Array.<number>
Takes the ground truth and a single recording.
Both gtNotes and recNotes must be sorted by note start time ascending.
**Kind**: global function
**Returns**: Array.<number> - for each note the difference in start time to the closest
recorded note
| Param | Type | Description |
| --- | --- | --- |
| gtNotes | [Array.<Note>](#Note) | ground truth notes |
| recNotes | [Array.<Note>](#Note) | recorded notes |
## getNoteErrors(expectedNote, actualNote) ⇒ Array.<string>
**Kind**: global function
**Returns**: Array.<string> - errors
**Todo**
- [ ] untested, unused
| Param | Type | Description |
| --- | --- | --- |
| expectedNote | [Note](#Note) | a note |
| actualNote | [Note](#Note) | a note |
## getChordErrors(expectedChord, actualChord) ⇒ Array.<string>
**Kind**: global function
**Returns**: Array.<string> - errors
**Todo**
- [ ] NYI
| Param | Type | Description |
| --- | --- | --- |
| expectedChord | [Array.<Note>](#Note) | a chord |
| actualChord | [Array.<Note>](#Note) | a chord |
## noteCountDifference(notesA, notesB) ⇒ number
**Kind**: global function
**Returns**: number - difference
| Param | Type | Description |
| --- | --- | --- |
| notesA | [Array.<Note>](#Note) | notes |
| notesB | [Array.<Note>](#Note) | other notes |
## durationDifference(notesA, notesB) ⇒ number
**Kind**: global function
**Returns**: number - difference
| Param | Type | Description |
| --- | --- | --- |
| notesA | [Array.<Note>](#Note) | notes |
| notesB | [Array.<Note>](#Note) | other notes |
## pitchHistogramDistance(notesA, notesB) ⇒ number
**Kind**: global function
**Returns**: number - distance
| Param | Type | Description |
| --- | --- | --- |
| notesA | [Array.<Note>](#Note) | notes |
| notesB | [Array.<Note>](#Note) | other notes |
## timeBinningDistance(notesA, notesB, binSize) ⇒ number
**Kind**: global function
**Returns**: number - distance
**Todo**
- [ ] allow to re-use a typed array for all recordings to save time and space?
| Param | Type | Description |
| --- | --- | --- |
| notesA | [Array.<Note>](#Note) | notes |
| notesB | [Array.<Note>](#Note) | other notes |
| binSize | number | bin size in seconds |
## timeBinningDistance2(notesA, notesB, binSize) ⇒ number
**Kind**: global function
**Returns**: number - distance
**Todo**
- [ ] allow to re-use a typed array for all recordings to save time and space?
| Param | Type | Description |
| --- | --- | --- |
| notesA | [Array.<Note>](#Note) | notes |
| notesB | [Array.<Note>](#Note) | other notes |
| binSize | number | bin size in seconds |
## notesCount(notes) ⇒ number
Computes the number of notes
**Kind**: global function
**Returns**: number - number of notes
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## duration(notes) ⇒ number
Computes played duration
**Kind**: global function
**Returns**: number - duration
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## notesPerSecond(notes) ⇒ number
Computes the number of notes played per second
**Kind**: global function
**Returns**: number - number of notes per second
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## notesPerBeat(notes, [bpm]) ⇒ number
Computes the number of notes played per relative time (beat)
**Kind**: global function
**Returns**: number - number of notes per beat
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| notes | [Array.<Note>](#Note) | | notes |
| [bpm] | number | 120 | tempo in bpm |
## differentNotesUsed(notes, mode) ⇒ Array.<object>
Computes the number of different notes used in different modi.
- Pitch: note and octave are considered
- Chroma: only note without octave considered, e.g., C4 == C5
- Fretboard position: tuple (string, fret) will be compared
**Kind**: global function
**Returns**: Array.<object> - note and usage count
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| mode | 'pitch' \| 'chroma' \| 'fretboardPos' | mode |
## ratioNotesInSet(notes, set) ⇒ number
Computes the ratio of notes that are in the given set.
Can be used for checking how many notes that were played are part of a
musical scale, by passing the notes of this scale as set.
**Kind**: global function
**Returns**: number - ratio of notes inside set
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
| set | Set | set of note names, e.g. C, D# (no flats) |
**Example**
```js
const cMaj = new Set(...'CDEFGAB');
const ratio = ratioNotesInSet(notes, cMaj);
```
## pitchMeanAndVariance(notes) ⇒ object
Computes the mean and variance of played pitches
**Kind**: global function
**Returns**: object - {mean, variance}
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## pitchExtent(notes) ⇒ Array.<number>
Computes the min and max pitch
**Kind**: global function
**Returns**: Array.<number> - min and max pitch
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## intervalMeanAndVariance(notes) ⇒ object
Computes the mean and variance of played intervals
**Kind**: global function
**Returns**: object - {mean, variance}
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## dynamicsMeanAndVariance(notes) ⇒ object
Computes the mean and variance of played dynamics
**Kind**: global function
**Returns**: object - {mean, variance}
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## durationMeanAndVariance(notes) ⇒ object
Computes the mean and variance of played dynamics
**Kind**: global function
**Returns**: object - {mean, variance}
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## onsetDiffMeanAndVariance(notes) ⇒ object
Computes the mean and variance of onset (start time) differences between
consecutive notes.
**Kind**: global function
**Returns**: object - {mean, variance}
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## guitarStringSkips(notes, [skipped]) ⇒ number
Computs the ratio of notes for which one string (or more) where skipped
between the one before and the current note.
The `skipped` parameter set the minimum amount of strings between the two
notes, e.g., going from string 1 to 3 means that one (string 2) was skipped.
**Kind**: global function
**Returns**: number - ratio of notes where `skipped` string where skipped
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| notes | [Array.<GuitarNote>](#GuitarNote) | | notes |
| [skipped] | number | 0 | number of strings skipped between notes |
## guitarFretSkips(notes, [skipped]) ⇒ number
Computs the ratio of notes for which one fret (or more) where skipped between
the one before and the current note.
The `skipped` parameter set the minimum amount of fret between the two
notes, e.g., going from fret 1 to 3 means that one (fret 2) was skipped.
**Kind**: global function
**Returns**: number - ratio of notes where `skipped` string where skipped
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| notes | [Array.<GuitarNote>](#GuitarNote) | | notes |
| [skipped] | number | 0 | number of fret skipped between notes |
## harmonySizeDistribution(harmonies) ⇒ Array.<object>
Counts how often harmonies of different sizes occur
**Kind**: global function
**Returns**: Array.<object> - {size, count}
| Param | Type | Description |
| --- | --- | --- |
| harmonies | Array.<Array.<Note>> | groups of notes that belong to harmonies |
**Example**
```js
// You can use different grouping functions as well, see chords/Chords.js
const harmonies = Chords.detectChordsBySimilarStart(notes, theshold);
const sizeDistr = harmonySizeDistribution(harmonies);
```
## harmonySingleToMultiRatio(harmonies) ⇒ number
Determines the ratio of single notes to multi-note harmonies
**Kind**: global function
**Returns**: number - ratio of single notes to multi-note harmonies
| Param | Type | Description |
| --- | --- | --- |
| harmonies | Array.<Array.<Note>> | groups of notes that belong to harmonies |
## notesToIntervals(notes) ⇒ Array.<number>
Computes the pitch intervals between consecutive notes
**Kind**: global function
**Returns**: Array.<number> - pitch intervals
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## notesToOnsetDifferences(notes) ⇒ Array.<number>
Computes the start time differences between consecutive notes
**Kind**: global function
**Returns**: Array.<number> - start time differences
| Param | Type | Description |
| --- | --- | --- |
| notes | [Array.<Note>](#Note) | notes |
## compress(sequence) ⇒ object
Compresses a sequence by detecting immediately repeating subsequences
hierarchically. Optimal result but high performance complexity.
**Kind**: global function
**Returns**: object - compressed hierarchy
**Todo**
- [ ] Link to observable demo
| Param | Type | Description |
| --- | --- | --- |
| sequence | Array | array with immediately repeating subsequences |
## getImmediateRepetitions(sequence) ⇒ Array.<object>
Finds all immediate repetitions in a given sequence.
**Kind**: global function
**Returns**: Array.<object> - result
**Todo**
- [ ] implement a mode that just looks for the best one, instead of later
sorting all found ones (will be faster since less sequence.slice() happens)
Still needs to keep all results with the same score
| Param | Type | Description |
| --- | --- | --- |
| sequence | Array | array with immediately repeating subsequences |
## decompress(tree) ⇒ Array
Restores the original array/sequence from the compressed hierarchy.
**Kind**: global function
**Returns**: Array - decompressed sequence
| Param | Type | Description |
| --- | --- | --- |
| tree | object | compressed hierarchy |
## summary(tree) ⇒ Array
Returns the summary of a hierachy, leaving out information about repetitions.
**Kind**: global function
**Returns**: Array - summary
| Param | Type | Description |
| --- | --- | --- |
| tree | object | compressed hierarchy |
**Example**
```js
const arr = '12312345656'.split('')
const h = compress(arr)
summary(h).join('')
// '123456'
```
## toString(tree, separator) ⇒ string
Formats a compressed hierarchy into a readable string, for example:
"1222333222333" => "1 (2x (3x 2) (3x 3))"
**Kind**: global function
**Returns**: string - result
| Param | Type | Description |
| --- | --- | --- |
| tree | object | compressed hierarchy |
| separator | string | separator |
## compressionRate(compressed) ⇒ number
Calculates the compression rate in [0, 1] for a result of compress().
**Kind**: global function
**Returns**: number - compression ratio
**Throws**:
- 'Invalid hierarchy' for invalid hierarchy
| Param | Type | Description |
| --- | --- | --- |
| compressed | object | compressed hierachy |
## getNGrams(string, length) ⇒ Map.<string, number>
Calculates all n-grams with a specified length
**Kind**: global function
**Returns**: Map.<string, number> - maps n-gram to its number of occurences
| Param | Type | Description |
| --- | --- | --- |
| string | string | a string |
| length | number | length (n) of n-grams |
## getNGramsForArray(array, length) ⇒ Map.<string, object>
Calculates all n-grams with a specified length
**Kind**: global function
**Returns**: Map.<string, object> - maps n-gram, joined with ' ', to its number of
occurences and value
| Param | Type | Description |
| --- | --- | --- |
| array | Array | an array of primitive data types |
| length | number | length (n) of n-grams |
## simplify(objectArray, keys)
Simplifies each object in an array by copying only some keys and their values
**Kind**: global function
**Todo.**: move to testing lib
| Param | Type | Description |
| --- | --- | --- |
| objectArray | Array.<object> | array with objects |
| keys | Array.<string> | keys to copy |
## getMusicPiecesFromBothFormats(fileBaseName) ⇒ Object
Given a file name (without extension), this function will read a .mid and a
.musicxml file and parse both to a MusicPiece before returning those.
**Kind**: global function
**Returns**: Object - two MusicPiece objects
| Param | Type | Description |
| --- | --- | --- |
| fileBaseName | string | file name without extension |
## getColorLightness(color) ⇒ number
Determines the perceptual lightness of an HTML color
**Kind**: global function
**Returns**: number - lightness in [0, 100]
**See**: https://stackoverflow.com/a/596241 (but normalizing to 0, 100)
| Param | Type | Description |
| --- | --- | --- |
| color | string | HTML color specifier |
## averageColor(colors) ⇒ string
Determines the average of mutliple given colors
**Kind**: global function
**Returns**: string - average as RGB string
| Param | Type | Description |
| --- | --- | --- |
| colors | Array.<string> | HTML color specifiers |
## setOpacity(color, [opacity]) ⇒ string
Sets a color's opacity.
Does not support colors in rgba format.
**Kind**: global function
**Returns**: string - color as RGBA string
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| color | string | | valid HTML color identifier |
| [opacity] | number | 1 | opacity from 0 to 1 |
## setSaturation(color, [saturation]) ⇒ string
Sets a color's saturation.
Does not support colors in rgba format.
**Kind**: global function
**Returns**: string - color as RGBA string
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| color | string | | valid HTML color identifier |
| [saturation] | number | 1 | saturation from 0 to 1 |