<commit_before>Teoria.js
=========

Teoria.js is a lightweight and fast JavaScript framework
for music theory, both Jazz and Classical. It aims at providing an intuitive
programming interface for music software (such as Sheet Readers,
Sheet Writers, MIDI Players etc.).

Features
---------

 - A note object (`teoria.note`), which understands alterations, octaves,
 keynumber, frequency and etc. and Helmholtz notation

 - A chord object (`teoria.chord`), which understands everything
 from simple major/minor chords to advanced Jazz chords (Ab#5b9, F(#11) and such)

 - A scale object (`teoria.scale`), The scale object is a powerful presentation of
 a scale, which support quite a few handy methods. A scale can either be
 constructed from the predefined scales, which by default contains the 7 modes
 (Ionian, Dorian, Phrygian etc.) a major and minor pentatonic and the harmonic
 chromatic scale or from a arbitary array of intervals. The scale object
 also supports solfège, which makes it perfect for tutorials on sight reading.

 - An interval object (`teoria.interval`), which makes it easy to find the
 interval between to notes, or find a note which is a given interval from a note.
 There's also support for counting the interval span in semitones and inverting the
 interval.

Building
--------

Building the library is simple. Just fetch the code:

```bash
git clone git://github.com/saebekassebil/teoria
```

Install Jake (the build tool)

```bash
npm install -g jake
```

Enter the directory, and install the dependencies:
```bash
cd teoria && npm install
```

And build the library! You can build a minified version, by adding `[minify]` to the command:
```bash
jake build
# or
jake build[minify]
```

Syntax
---------

This is just a short introduction to what the framework can be used to.
For a technical library reference, look further down this document.

```javascript

// Create notes:
var a4 = teoria.note('a4');       // Scientific notation
var g5 = teoria.note("g''");      // Helmholtz notation
var c3 = teoria.note.fromKey(28); // From a piano key number

// Find and create notes based on intervals
teoria.interval(a4, g5);    // Returns a TeoriaInterval object representing a minor seventh
teoria.interval(a4, 'M6');  // Returns a TeoriaNote representing F#5
a4.interval('m3');          // Returns a TeoriaNote representing C#4
a4.interval(g5);            // Returns a TeoriaInterval object representing a minor seventh
a4.interval(teoria.note('bb5')).invert(); // Returns a TeoriaInterval representing a major seventh

// Create scales, based on notes.
a4.scale('mixolydian').simple();  // Returns: ["a", "b", "c#", "d", "e", "f#", "g"]
a4.scale('aeolian').simple();     // Returns: ["a", "b", "c", "d", "e", "f", "g"]
g5.scale('ionian').simple();      // Returns: ["g", "a", "b", "c", "d", "e", "f#"]
g5.scale('dorian');               // Returns a TeoriaScale object

// Create chords with the powerful chord parser
a4.chord('sus2').name;    // Returns the name of the chord: 'Asus2'
c3.chord('m').name;       // Reutns 'Cm'
teoria.chord('Ab#5b9');   // Returns a TeoriaChord object, representing a Ab#5b9 chord
g5.chord('dim');          // Returns a TeoriaChord object, representing a Gdim chord

// Calculate note frequencies or find the note corresponding to a frequency
teoria.note.fromFrequency(467); // Returns: {'note':{...},'cents':3.102831} -> A4# a little out of tune.
a4.fq(); // Outputs 440
g5.fq(); // Outputs 783.9908719634985

// teoria allows for crazy chaining:
teoria.note('a')    // Create a note, A3
  .scale('lydian')  // Create a lydian scale with that note as root (A lydian)
  .interval('M2')   // Transpose the whole scale a major second up (B lydian)
  .get('third')     // Get the third note of the scale (D#4)
  .chord('maj9')    // Create a maj9 chord with that note as root (D#maj9)
  .toString();      // Make a string representation: 'D#maj9'
```

Documentation
------------------------


## TeoriaNote(name[, duration])
 - This function construct a teoria.note object.

*name* - The name argument is the note name as a string. The note can both
be expressed in scientific and Helmholtz notation.
Some examples of valid note names: `Eb4`, `C#,,`, `C4`, `d#''`, `Ab2`

*duration* - The duration argument is an optional `object` argument.
The object has two also optional parameters:

 - `value` - A `number` corresponding to the value of the duration, such that:
`1 = whole`, `2 = half (minim)`, `4 = quarter`, `8 = eight`

 - `dots` - The number of dots attached to the note. Defaults to `0`.

### teoria.note (TeoriaNote)

The teoria.note object is teoria's interpretation and representation of a
musical note. When calling teoria.note you're actually instantiating a
`TeoriaNote` object.

### teoria.note.fromKey(key)
A static method that returns an instance of TeoriaNote set to the note at the given piano key

### teoria.note.fromFrequency(fq)
A static method returns an object containing two elements:

*note* - A `TeoriaNote` which corresponds to the closest note with the given frequency

*cents* - A number value of how many cents the note is out of tune

### teoria.note.fromMIDI(note)
 - Returns an instance of TeoriaNote set to the corresponding MIDI note value.
<commit_msg>Elaborate on teoria.note.fromKey method in the documentation. Fixes #27<commit_after>Teoria.js
=========

Teoria.js is a lightweight and fast JavaScript framework
for music theory, both Jazz and Classical. It aims at providing an intuitive
programming interface for music software (such as Sheet Readers,
Sheet Writers, MIDI Players etc.).

Features
---------

 - A note object (`teoria.note`), which understands alterations, octaves,
 keynumber, frequency and etc. and Helmholtz notation

 - A chord object (`teoria.chord`), which understands everything
 from simple major/minor chords to advanced Jazz chords (Ab#5b9, F(#11) and such)

 - A scale object (`teoria.scale`), The scale object is a powerful presentation of
 a scale, which support quite a few handy methods. A scale can either be
 constructed from the predefined scales, which by default contains the 7 modes
 (Ionian, Dorian, Phrygian etc.) a major and minor pentatonic and the harmonic
 chromatic scale or from a arbitary array of intervals. The scale object
 also supports solfège, which makes it perfect for tutorials on sight reading.

 - An interval object (`teoria.interval`), which makes it easy to find the
 interval between to notes, or find a note which is a given interval from a note.
 There's also support for counting the interval span in semitones and inverting the
 interval.

Building
--------

Building the library is simple. Just fetch the code:

```bash
git clone git://github.com/saebekassebil/teoria
```

Install Jake (the build tool)

```bash
npm install -g jake
```

Enter the directory, and install the dependencies:
```bash
cd teoria && npm install
```

And build the library! You can build a minified version, by adding `[minify]` to the command:
```bash
jake build
# or
jake build[minify]
```

Syntax
---------

This is just a short introduction to what the framework can be used to.
For a technical library reference, look further down this document.

```javascript

// Create notes:
var a4 = teoria.note('a4');       // Scientific notation
var g5 = teoria.note("g''");      // Helmholtz notation
var c3 = teoria.note.fromKey(28); // From a piano key number

// Find and create notes based on intervals
teoria.interval(a4, g5);    // Returns a TeoriaInterval object representing a minor seventh
teoria.interval(a4, 'M6');  // Returns a TeoriaNote representing F#5
a4.interval('m3');          // Returns a TeoriaNote representing C#4
a4.interval(g5);            // Returns a TeoriaInterval object representing a minor seventh
a4.interval(teoria.note('bb5')).invert(); // Returns a TeoriaInterval representing a major seventh

// Create scales, based on notes.
a4.scale('mixolydian').simple();  // Returns: ["a", "b", "c#", "d", "e", "f#", "g"]
a4.scale('aeolian').simple();     // Returns: ["a", "b", "c", "d", "e", "f", "g"]
g5.scale('ionian').simple();      // Returns: ["g", "a", "b", "c", "d", "e", "f#"]
g5.scale('dorian');               // Returns a TeoriaScale object

// Create chords with the powerful chord parser
a4.chord('sus2').name;    // Returns the name of the chord: 'Asus2'
c3.chord('m').name;       // Reutns 'Cm'
teoria.chord('Ab#5b9');   // Returns a TeoriaChord object, representing a Ab#5b9 chord
g5.chord('dim');          // Returns a TeoriaChord object, representing a Gdim chord

// Calculate note frequencies or find the note corresponding to a frequency
teoria.note.fromFrequency(467); // Returns: {'note':{...},'cents':3.102831} -> A4# a little out of tune.
a4.fq(); // Outputs 440
g5.fq(); // Outputs 783.9908719634985

// teoria allows for crazy chaining:
teoria.note('a')    // Create a note, A3
  .scale('lydian')  // Create a lydian scale with that note as root (A lydian)
  .interval('M2')   // Transpose the whole scale a major second up (B lydian)
  .get('third')     // Get the third note of the scale (D#4)
  .chord('maj9')    // Create a maj9 chord with that note as root (D#maj9)
  .toString();      // Make a string representation: 'D#maj9'
```

Documentation
------------------------


## TeoriaNote(name[, duration])
 - This function construct a teoria.note object.

*name* - The name argument is the note name as a string. The note can both
be expressed in scientific and Helmholtz notation.
Some examples of valid note names: `Eb4`, `C#,,`, `C4`, `d#''`, `Ab2`

*duration* - The duration argument is an optional `object` argument.
The object has two also optional parameters:

 - `value` - A `number` corresponding to the value of the duration, such that:
`1 = whole`, `2 = half (minim)`, `4 = quarter`, `8 = eight`

 - `dots` - The number of dots attached to the note. Defaults to `0`.

### teoria.note (TeoriaNote)

The teoria.note object is teoria's interpretation and representation of a
musical note. When calling teoria.note you're actually instantiating a
`TeoriaNote` object.

### teoria.note.fromKey(key)
A static method that returns an instance of TeoriaNote set to the note
at the given 88 key piano position, where A0 is key number 1.
See [Wikipedia's piano key article](http://en.wikipedia.org/wiki/Piano_key_frequencies)
for more information.

### teoria.note.fromFrequency(fq)
A static method returns an object containing two elements:

*note* - A `TeoriaNote` which corresponds to the closest note with the given frequency

*cents* - A number value of how many cents the note is out of tune

### teoria.note.fromMIDI(note)
 - Returns an instance of TeoriaNote set to the corresponding MIDI note value.

{'fraction_non_alphanumeric': 0.12300364247688428, 'fraction_numerical': 0.01606425702811245, 'mean_word_length': 3.6964912280701756, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7671899', 'n_tokens_mistral': 3320, 'n_tokens_neox': 3133, 'n_words': 1380}