MusicMachineA MusicMachine configured to create guides that generate Cantus Firmi
GuidedMusicMachinecreate a new GuidedMusicMachine configured with a Cantus Firmus grammar
MusicMachine filter generator that filters out notes which are OK in the moment but that preclude the creation of a valid CF. For example, if maxRange is 8 and the cf goes down 8 from the first note, there cannot be a climax as the cf must end on tonic again.
MusicMachine filter that ensures valid melodic outlines (a group of notes that move in the same direction)
MusicMachine filter that avoids leaping back to the same note after leaving it via a leap (no 1 3 1)
MusicMachine filter that avoids patterns of length 2 or 3 such as 1 2 1 2 or 1 2 3 1 2 3
Stringcreates a simple tabular visualization of the cantus firmus
numbergiven an array of pitch strings, gives the index of the start of the last melodic outline (the first index of a group of notes moving in the same direction)
Array.<string>helper function to sort an array of pitches from lowest to highest
stringa string consisting of a music Letter [A-G], optional accidental, and optional octave number
stringa string consisting of a PitchString and a mode name seperated by whitespace
object[Array.<PitchString>](#PitchString)
* [.addNote(pitch)](#CantusFirmus+addNote)
* [.pop()](#CantusFirmus+pop) ⇒ [PitchString](#PitchString)
* [.choices([nDeep])](#CantusFirmus+choices) ⇒ [Array.<PitchString>](#PitchString) | [Array.<TreeNode>](#TreeNode)
* [.isValid()](#CantusFirmus+isValid) ⇒ boolean
* [.toString()](#CantusFirmus+toString) ⇒ string
* [.print()](#CantusFirmus+print) ⇒ string
* [.key()](#CantusFirmus+key) ⇒ [KeyString](#KeyString)
### new CantusFirmus([key], [maxRange], [maxLength])
create a CantusFirmus that follows the rules of species counterpoint
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [key] | [KeyString](#KeyString) | 'C major' | the key of this cf |
| [maxRange] | number | 10 | the max range this machine will allow |
| [maxLength] | number | 16 | the maxLength of this machine |
### cantusFirmus.cf() ⇒ [Array.<PitchString>](#PitchString)
get the current cantus firmus
**Kind**: instance method of [CantusFirmus](#CantusFirmus)
**Returns**: [Array.<PitchString>](#PitchString) - an array of pitch strings
### cantusFirmus.addNote(pitch)
adds the given pitch to the cantus firmus
**Kind**: instance method of [CantusFirmus](#CantusFirmus)
**Throws**:
- throws an error if given pitch is not in the
current set of [CantusFirmus#nextNoteChoices](CantusFirmus#nextNoteChoices)
| Param | Type | Description |
| --- | --- | --- |
| pitch | [PitchString](#PitchString) | a pitch string in the current set of [CantusFirmus#nextNoteChoices](CantusFirmus#nextNoteChoices) |
### cantusFirmus.pop() ⇒ [PitchString](#PitchString)
pop the last note choice off the cantus firmus
**Kind**: instance method of [CantusFirmus](#CantusFirmus)
**Returns**: [PitchString](#PitchString) - the last pitch string of the cantus firmus
submitted through [addNote](#CantusFirmus+addNote)
**Throws**:
- throws an error if called when cantus firmus is empty
### cantusFirmus.choices([nDeep]) ⇒ [Array.<PitchString>](#PitchString) | [Array.<TreeNode>](#TreeNode)
returns an array of all possible next pitches, or an array of
nDeep [TreeNodes](#TreeNode).
**Kind**: instance method of [CantusFirmus](#CantusFirmus)
**Returns**: [Array.<PitchString>](#PitchString) | [Array.<TreeNode>](#TreeNode) - if nDeep=1, an array of pitch strings, else
an array of nDeep [TreeNodes](TreeNodes)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [nDeep] | number | 1 | will search for nDeep possible choices |
### cantusFirmus.isValid() ⇒ boolean
is the current cantus firmus a complete and valid cantus firmus?
**Kind**: instance method of [CantusFirmus](#CantusFirmus)
**Returns**: boolean - is the current cantus firmus a complete and valid cantus firmus?
### cantusFirmus.toString() ⇒ string
**Kind**: instance method of [CantusFirmus](#CantusFirmus)
**Returns**: string - a space separated string with the pitches of this cantus firmus
### cantusFirmus.print() ⇒ string
creates a simple tabular visualization of the cantus firmus
**Kind**: instance method of [CantusFirmus](#CantusFirmus)
**Returns**: string - a simple tabular visualization of the cantus firmus
**See**: [prettyPrintCf](#prettyPrintCf)
### cantusFirmus.key() ⇒ [KeyString](#KeyString)
**Kind**: instance method of [CantusFirmus](#CantusFirmus)
**Returns**: [KeyString](#KeyString) - the key of this cantus firmus
## cfMachine : MusicMachine
A [MusicMachine](https://github.com/jrleszcz/music-machine/blob/master/api.md#MusicMachine)
configured to create guides that generate Cantus Firmi
**Kind**: global variable
## createCFguide([key], [maxRange], [maxLength]) ⇒ GuidedMusicMachine
create a new GuidedMusicMachine configured with a Cantus Firmus grammar
**Kind**: global function
**Returns**: GuidedMusicMachine - a new GuidedMusicMachine configured to create a cantus firmus
**See**: [GuidedMusicMachine](https://github.com/jrleszcz/music-machine/blob/master/api.md#GuidedMusicMachine)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [key] | [KeyString](#KeyString) | 'C major' | the key of this guide's construction |
| [maxRange] | number | 10 | the max range of this guide's construction |
| [maxLength] | number | 16 | the maxLength of this guide's construction |
## foresightFilterGenerator()
MusicMachine filter generator that filters out notes which
are OK in the moment but that preclude the creation of a valid CF.
For example, if maxRange is 8 and the cf goes down 8 from the first note,
there cannot be a climax as the cf must end on tonic again.
**Kind**: global function
## outlineFilter()
MusicMachine filter that ensures valid melodic outlines (a group of notes that move in the same direction)
**Kind**: global function
## noLeapBackFilter()
MusicMachine filter that avoids leaping back to the same note after
leaving it via a leap (no 1 3 1)
**Kind**: global function
## patternFilter()
MusicMachine filter that avoids patterns of length 2 or 3
such as 1 2 1 2 or 1 2 3 1 2 3
**Kind**: global function
## prettyPrintCf(cantusFirmus) ⇒ String
creates a simple tabular visualization of the cantus firmus
**Kind**: global function
**Returns**: String - a tabular representation of the cantus firmus
| Param | Type | Description |
| --- | --- | --- |
| cantusFirmus | [CantusFirmus](#CantusFirmus) | the cantus firmus to visualize |
**Example**
```js
var cf = new CantusFirmus('D minor')
'D4 E4 F4 C4 D4 F4 E4 G4 Bb3 C4 F4 E4 D4'.split(' ').forEach(cf.addNote)
prettyPrintCf(cf) =>
// G4 o
// F4 o o o
// E4 o o o
// D4 o o o
// C4 o o
// Bb3 o
// D4 E4 F4 C4 D4 F4 E4 G4 Bb3 C4 F4 E4 D4
```
## indexOfLastOutline(construction) ⇒ number
given an array of pitch strings, gives the index of the start of the last melodic outline
(the first index of a group of notes moving in the same direction)
**Kind**: global function
**Returns**: number - the index of the last direction change or 0 if there is no direction change
| Param | Type | Description |
| --- | --- | --- |
| construction | [Array.<PitchString>](#PitchString) | an array of pitches |
## sortPitches(pitches) ⇒ Array.<string>
helper function to sort an array of pitches from lowest to highest
**Kind**: global function
**Returns**: Array.<string> - a new clone of the provided pitch string
array sorted from low pitch to high pitch
| Param | Type | Description |
| --- | --- | --- |
| pitches | Array.<string> | an array of pitch strings |
## PitchString : string
a string consisting of a music Letter [A-G], optional accidental,
and optional octave number
**Kind**: global typedef
**Example**
```js
'C4' // middle C on a piano, the fourth octave
'Eb3' // Eb in octave 3
'F#' // no octave number provided, a pitch class
'F##' // F double sharp
'Dbb' // D double flat
```
## KeyString : string
a string consisting of a [PitchString](#PitchString) and a mode name
seperated by whitespace
**Kind**: global typedef
**Example**
```js
'Eb major'
'C minor'
'F# dorian'
```
## TreeNode : object
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| val | [PitchString](#PitchString) | a pitch string |
| next | [Array.<TreeNode>](#TreeNode) | a list of TreeNodes this node links to |