# musy


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

# Installation

``` sh
pip install musy
```

# How to use

## Note

``` python
from musy import Note, Chord, Scale
```

The [`Note`](https://CarloLepelaars.github.io/musy/core.html#note) is
the basic building block from which you can create chords and songs.

``` python
c_sharp = Note("C#")
c_sharp
```

    musy.core.Note(note='C#', oct=4)

Notes can be added and subtracted to form new notes. Each added integer
represents a semitone.

``` python
c_sharp + 1
```

    musy.core.Note(note='D', oct=4)

``` python
c_sharp - 1
```

    musy.core.Note(note='C', oct=4)

``` python
c_sharp + 14
```

    musy.core.Note(note='D#', oct=5)

Notes can be compared using familiar Python operators.

``` python
c = Note("C")
g = Note("G")

c < g
```

    True

Octaves can make a difference in comparisons.

``` python
Note("C", oct=4) >= Note("G", oct=3)
```

    True

[`Interval`](https://CarloLepelaars.github.io/musy/core.html#interval)
objects can be obtained by calling `interval` on two notes or using the
`&` operator.

``` python
f_sharp = Note("F#")

P4 = c_sharp & f_sharp
P4
```

    perfect fourth (4)

``` python
P4.semitones, P4.long, P4.short, P4.type()
```

    (5, 'perfect fourth', '4', 'Contextual')

Intervals can also be compared.

``` python
P5 = c & g
P5
```

    perfect fifth (5)

``` python
P5.semitones, P5.long, P5.short, P5.type()
```

    (7, 'perfect fifth', '5', 'Perfect Consonant')

``` python
P4 != P5
```

    True

``` python
P4 < P5
```

    True

Notes can be converted to its relative major or minor. As can be found
on the circle of fifths.

``` python
Note("C").minor()
```

    musy.core.Note(note='A', oct=4)

``` python
Note("C#").major()
```

    musy.core.Note(note='E', oct=4)

# Chord

The [`Chord`](https://CarloLepelaars.github.io/musy/core.html#chord) is
a collection of
[`Note`](https://CarloLepelaars.github.io/musy/core.html#note) objects
played together.

``` python
c_major = Chord(["C", "E", "G"])
c_major
```

    Chord: 'C major triad'. Notes: ['C4', 'E4', 'G4']

[`Chord`](https://CarloLepelaars.github.io/musy/core.html#chord) objects
can be initialized from shorthand notation.

``` python
cmaj7 = Chord.from_short("Cmaj7")
cmaj7
```

    Chord: 'C major seventh'. Notes: ['C4', 'E4', 'G4', 'B4']

Chords can also be inverted with `invert`.

``` python
# Get 1st inversion chord of C major 7th
cmaj7.invert(1)
```

    Chord: 'C major seventh, first inversion'. Notes: ['E4', 'G4', 'B4', 'C5']

Like [`Note`](https://CarloLepelaars.github.io/musy/core.html#note)
objects,
[`Chord`](https://CarloLepelaars.github.io/musy/core.html#chord) objects
can be added and subtracted to transpose them.

``` python
cmaj7 + 2
```

    Chord: 'D major seventh'. Notes: ['D4', 'F#4', 'A4', 'C#5']

Notes can be multiplied to create chords.

``` python
Note("C") * Note("E") * Note("G")
```

    Chord: 'C major triad'. Notes: ['C4', 'E4', 'G4']

For advanced usage there is even a way to create
[`PolyChord`](https://CarloLepelaars.github.io/musy/core.html#polychord)
objects. These are most naturally created by multiplying
[`Chord`](https://CarloLepelaars.github.io/musy/core.html#chord)
objects.

``` python
Chord.from_short("C") * Chord.from_short("Bbmaj7").invert(3)
```

    PolyChord: 'C major triad|Bb major seventh, third inversion'. Notes: ['C4', 'E4', 'G4', 'A4', 'Bb5', 'D5', 'F5']

# Scale

[`Scale`](https://CarloLepelaars.github.io/musy/core.html#scale) objects
are collections of intervals from which we can generate notes and chords
around a root note.

``` python
dorian = Scale("dorian")
dorian
```

    Scale: Dorian. Intervals: ['1', '2', 'b3', '4', '5', '6', 'b7']

When given a root note,
[`Scale`](https://CarloLepelaars.github.io/musy/core.html#scale)
generates the notes of the scale.

``` python
dorian.get_notes("C")
```

    [musy.core.Note(note='C', oct=4),
     musy.core.Note(note='D', oct=4),
     musy.core.Note(note='D#', oct=4),
     musy.core.Note(note='F', oct=4),
     musy.core.Note(note='G', oct=4),
     musy.core.Note(note='A', oct=4),
     musy.core.Note(note='A#', oct=4)]

Intervals can be obtained.

``` python
dorian.get_interval_names()
```

    ['major second',
     'minor third',
     'perfect fourth',
     'perfect fifth',
     'major sixth',
     'minor seventh']

Triads and seventh chords in the scale can be generated around a root
note.

``` python
dorian.get_triads("D")
```

    [Chord: 'D minor triad'. Notes: ['D4', 'F4', 'A4'],
     Chord: 'E minor triad'. Notes: ['E4', 'G4', 'B4'],
     Chord: 'F major triad'. Notes: ['F4', 'A4', 'C4'],
     Chord: 'G major triad'. Notes: ['G4', 'B4', 'D5'],
     Chord: 'A minor triad'. Notes: ['A4', 'C4', 'E5'],
     Chord: 'B diminished triad'. Notes: ['B4', 'D5', 'F5'],
     Chord: 'C major triad'. Notes: ['C5', 'E6', 'G6']]

``` python
dorian.get_sevenths("E")
```

    [Chord: 'E minor seventh'. Notes: ['E4', 'G4', 'B4', 'D4'],
     Chord: 'F# minor seventh'. Notes: ['F#4', 'A4', 'C#4', 'E5'],
     Chord: 'G major seventh'. Notes: ['G4', 'B4', 'D4', 'F#5'],
     Chord: 'A dominant seventh'. Notes: ['A4', 'C#4', 'E5', 'G5'],
     Chord: 'B minor seventh'. Notes: ['B4', 'D4', 'F#5', 'A5'],
     Chord: 'C# half diminished seventh'. Notes: ['C#5', 'E6', 'G6', 'B6'],
     Chord: 'D major seventh'. Notes: ['D5', 'F#6', 'A6', 'C#6']]

All information can be conveniently retrieved and displayed as a Pandas
DataFrame with `to_frame`.

``` python
dorian.to_frame(root="E")
```

<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }
&#10;    .dataframe tbody tr th {
        vertical-align: top;
    }
&#10;    .dataframe thead th {
        text-align: right;
    }
</style>

|  | Intervals | Relative Semitones | Absolute Semitones | Notes | Triads | Seventh Chords |
|----|----|----|----|----|----|----|
| 0 | 1 | 0 | 2 | E | E minor triad | E minor seventh |
| 1 | 2 | 2 | 1 | F# | F# minor triad | F# minor seventh |
| 2 | b3 | 3 | 2 | G | G major triad | G major seventh |
| 3 | 4 | 5 | 2 | A | A major triad | A dominant seventh |
| 4 | 5 | 7 | 2 | B | B minor triad | B minor seventh |
| 5 | 6 | 9 | 1 | C# | C# diminished triad | C# half diminished seventh |
| 6 | b7 | 10 | 2 | D | D major triad | D major seventh |

</div>

Consult
[`Scale.available_scales`](https://CarloLepelaars.github.io/musy/core.html#scale.available_scales)
for a list of available scales. If a scale is not available, you can
create your own scale from intervals.

``` python
persian = Scale.from_intervals("persian", ["1", "b2", "3", "4", "b5", "b6", "7"])
persian
```

    Scale: Persian. Intervals: ['1', 'b2', '3', '4', 'b5', 'b6', '7']

``` python
persian.get_notes("C")
```

    [musy.core.Note(note='C', oct=4),
     musy.core.Note(note='C#', oct=4),
     musy.core.Note(note='E', oct=4),
     musy.core.Note(note='F', oct=4),
     musy.core.Note(note='F#', oct=4),
     musy.core.Note(note='G#', oct=4),
     musy.core.Note(note='B', oct=4)]

[`Note`](https://CarloLepelaars.github.io/musy/core.html#note),
[`Chord`](https://CarloLepelaars.github.io/musy/core.html#chord),
[`PolyChord`](https://CarloLepelaars.github.io/musy/core.html#polychord)
and [`Scale`](https://CarloLepelaars.github.io/musy/core.html#scale)
objects can all be heard by calling the `play` method on them.

# Visualization

`musy` objects can be visualized on a piano or guitar by providing a
list of [`Note`](https://CarloLepelaars.github.io/musy/core.html#note)
objects to the rendering method. Notes can easily be retrieved from
[`Chord`](https://CarloLepelaars.github.io/musy/core.html#chord) and
[`Scale`](https://CarloLepelaars.github.io/musy/core.html#scale)
objects.

``` python
from musy import Piano, Guitar

Piano()(Note("C#"))
```

    <style>
    .piano { background: #222; padding: 20px 0; position: relative; width: 480px; }
    .white-keys { display: flex; }
    .white-key {
        width: 40px; height: 125px; background: #fff;
        border: 1px solid #000;
        color: #111; font-size: 18px; text-align: center; line-height: 200px; font-family: Arial;
        position: relative; z-index: 1;
    }
    .black-key {
        width: 20px; height: 80px; background: #000; color: #fff;
        border: 1px solid #333; position: absolute; z-index: 2;
        text-align: center; line-height: 100px; font-family: Arial; font-size: 14px;
        left: 0; top: 20px; pointer-events: none;
    }
    .highlight { background: #ff0 !important; color: #000 !important; }
    .highlight-black { background: #ff0 !important; color: #000 !important; }
    </style>
    <div class="piano" style="width:440px"><div class="white-keys"><div class="white-key">C</div><div class="white-key">D</div><div class="white-key">E</div><div class="white-key">F</div><div class="white-key">G</div><div class="white-key">A</div><div class="white-key">B</div><div class="white-key">C</div><div class="white-key">D</div><div class="white-key">E</div><div class="white-key">F</div><div class="black-key highlight-black" style="left:26px">C#</div><div class="black-key" style="left:66px">D#</div><div class="black-key" style="left:146px">F#</div><div class="black-key" style="left:186px">G#</div><div class="black-key" style="left:226px">A#</div><div class="black-key highlight-black" style="left:306px">C#</div><div class="black-key" style="left:346px">D#</div><div class="black-key" style="left:426px">F#</div></div>

``` python
Piano()(list(Chord.from_short("Cmaj7")))
```

    <style>
    .piano { background: #222; padding: 20px 0; position: relative; width: 480px; }
    .white-keys { display: flex; }
    .white-key {
        width: 40px; height: 125px; background: #fff;
        border: 1px solid #000;
        color: #111; font-size: 18px; text-align: center; line-height: 200px; font-family: Arial;
        position: relative; z-index: 1;
    }
    .black-key {
        width: 20px; height: 80px; background: #000; color: #fff;
        border: 1px solid #333; position: absolute; z-index: 2;
        text-align: center; line-height: 100px; font-family: Arial; font-size: 14px;
        left: 0; top: 20px; pointer-events: none;
    }
    .highlight { background: #ff0 !important; color: #000 !important; }
    .highlight-black { background: #ff0 !important; color: #000 !important; }
    </style>
    <div class="piano" style="width:440px"><div class="white-keys"><div class="white-key highlight">C</div><div class="white-key">D</div><div class="white-key highlight">E</div><div class="white-key">F</div><div class="white-key highlight">G</div><div class="white-key">A</div><div class="white-key highlight">B</div><div class="white-key highlight">C</div><div class="white-key">D</div><div class="white-key highlight">E</div><div class="white-key">F</div><div class="black-key" style="left:26px">C#</div><div class="black-key" style="left:66px">D#</div><div class="black-key" style="left:146px">F#</div><div class="black-key" style="left:186px">G#</div><div class="black-key" style="left:226px">A#</div><div class="black-key" style="left:306px">C#</div><div class="black-key" style="left:346px">D#</div><div class="black-key" style="left:426px">F#</div></div>

``` python
Piano()(Scale("major").get_notes("D"))
```

    <style>
    .piano { background: #222; padding: 20px 0; position: relative; width: 480px; }
    .white-keys { display: flex; }
    .white-key {
        width: 40px; height: 125px; background: #fff;
        border: 1px solid #000;
        color: #111; font-size: 18px; text-align: center; line-height: 200px; font-family: Arial;
        position: relative; z-index: 1;
    }
    .black-key {
        width: 20px; height: 80px; background: #000; color: #fff;
        border: 1px solid #333; position: absolute; z-index: 2;
        text-align: center; line-height: 100px; font-family: Arial; font-size: 14px;
        left: 0; top: 20px; pointer-events: none;
    }
    .highlight { background: #ff0 !important; color: #000 !important; }
    .highlight-black { background: #ff0 !important; color: #000 !important; }
    </style>
    <div class="piano" style="width:440px"><div class="white-keys"><div class="white-key">C</div><div class="white-key highlight">D</div><div class="white-key highlight">E</div><div class="white-key">F</div><div class="white-key highlight">G</div><div class="white-key highlight">A</div><div class="white-key highlight">B</div><div class="white-key">C</div><div class="white-key highlight">D</div><div class="white-key highlight">E</div><div class="white-key">F</div><div class="black-key highlight-black" style="left:26px">C#</div><div class="black-key" style="left:66px">D#</div><div class="black-key highlight-black" style="left:146px">F#</div><div class="black-key" style="left:186px">G#</div><div class="black-key" style="left:226px">A#</div><div class="black-key highlight-black" style="left:306px">C#</div><div class="black-key" style="left:346px">D#</div><div class="black-key highlight-black" style="left:426px">F#</div></div>

``` python
Piano()(Scale("phrygian dominant").get_notes("D"))
```

    <style>
    .piano { background: #222; padding: 20px 0; position: relative; width: 480px; }
    .white-keys { display: flex; }
    .white-key {
        width: 40px; height: 125px; background: #fff;
        border: 1px solid #000;
        color: #111; font-size: 18px; text-align: center; line-height: 200px; font-family: Arial;
        position: relative; z-index: 1;
    }
    .black-key {
        width: 20px; height: 80px; background: #000; color: #fff;
        border: 1px solid #333; position: absolute; z-index: 2;
        text-align: center; line-height: 100px; font-family: Arial; font-size: 14px;
        left: 0; top: 20px; pointer-events: none;
    }
    .highlight { background: #ff0 !important; color: #000 !important; }
    .highlight-black { background: #ff0 !important; color: #000 !important; }
    </style>
    <div class="piano" style="width:440px"><div class="white-keys"><div class="white-key highlight">C</div><div class="white-key highlight">D</div><div class="white-key">E</div><div class="white-key">F</div><div class="white-key highlight">G</div><div class="white-key highlight">A</div><div class="white-key">B</div><div class="white-key highlight">C</div><div class="white-key highlight">D</div><div class="white-key">E</div><div class="white-key">F</div><div class="black-key" style="left:26px">C#</div><div class="black-key highlight-black" style="left:66px">D#</div><div class="black-key highlight-black" style="left:146px">F#</div><div class="black-key" style="left:186px">G#</div><div class="black-key highlight-black" style="left:226px">A#</div><div class="black-key" style="left:306px">C#</div><div class="black-key highlight-black" style="left:346px">D#</div><div class="black-key highlight-black" style="left:426px">F#</div></div>

``` python
Piano()(PolyChord([Chord.from_short("E"), Chord.from_short("Am")]))
```

    <style>
    .piano { background: #222; padding: 20px 0; position: relative; width: 480px; }
    .white-keys { display: flex; }
    .white-key {
        width: 40px; height: 125px; background: #fff;
        border: 1px solid #000;
        color: #111; font-size: 18px; text-align: center; line-height: 200px; font-family: Arial;
        position: relative; z-index: 1;
    }
    .black-key {
        width: 20px; height: 80px; background: #000; color: #fff;
        border: 1px solid #333; position: absolute; z-index: 2;
        text-align: center; line-height: 100px; font-family: Arial; font-size: 14px;
        left: 0; top: 20px; pointer-events: none;
    }
    .highlight { background: #ff0 !important; color: #000 !important; }
    .highlight-black { background: #ff0 !important; color: #000 !important; }
    </style>
    <div class="piano" style="width:440px"><div class="white-keys"><div class="white-key highlight">C</div><div class="white-key">D</div><div class="white-key highlight">E</div><div class="white-key">F</div><div class="white-key">G</div><div class="white-key highlight">A</div><div class="white-key highlight">B</div><div class="white-key highlight">C</div><div class="white-key">D</div><div class="white-key highlight">E</div><div class="white-key">F</div><div class="black-key" style="left:26px">C#</div><div class="black-key" style="left:66px">D#</div><div class="black-key" style="left:146px">F#</div><div class="black-key highlight-black" style="left:186px">G#</div><div class="black-key" style="left:226px">A#</div><div class="black-key" style="left:306px">C#</div><div class="black-key" style="left:346px">D#</div><div class="black-key" style="left:426px">F#</div></div>
