Metadata-Version: 2.1
Name: kord
Version: 1.5
Summary: a python framework for programming music applications
Home-page: https://github.com/synestematic/kord
Author: Federico Rizzo
Author-email: synestem@tic.com
License: MIT
Description: # kord
        kord is a python framework that provides programmers with a simple api for the creation of music-based applications. While it's mainly focused for theoretical purposes, some of it's more visually oriented features are well-suited for the generation of plucked-string instruments.
        
        <hr/>
        
        # api reference:
        
        ## kord.notes module:
        
        ### Note() class
        Note instances are the lowest-level objects of the framework and have 3 main attributes:
        
        ```
        * chr: str   ('C', 'D', 'E', 'F', 'G', 'A', 'B')
        * alt: str   ('b', 'bb', '', '#', '##')
        * oct: int   (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
        ```
        
        
        Only the `chr` argument is required to create an instance. Arguments `alt` and `oct` will default to `''` and `3` respectively.
        
        ```
        >>> from kord.notes import Note
        >>> e3, f3 = Note('e'), Note('f')
        >>> e3, f3
        (E³, F³) 
        >>> Note('B', 'b', 7)
        B♭⁷
        >>> Note('C', '#', 0)
        C♯⁰
        ```
        
        Notes with double alterations are supported but Notes with triple (or more) alterations raise InvalidAlteration Exceptions:
        
        ```
        >>> n3 = Note('A', 'bb', 1)
        >>> n3
        A𝄫¹
        >>> n4 = Note('F', '##', 1)
        >>> n4
        F𝄪¹
        >>> Note('G', '###')
        Traceback (most recent call last):
          File "<stdin>", line 1, in <module>
          ...
        kord.errors.InvalidAlteration: ###
        ```
        
        
         
        Intervals between note objects can be evaluated using the following operators:
        
        ```
        -   < >   <= >=   == !=   << >>
        ```
         
        These allow calculation of semitone deltas between notes as well as insights into their enharmonic relationships. Let's take a quick look at each operator separately:
        
        #### - operator
        
        This operator allows you to calculate the difference in semitones between two notes:
        
        ```
        >>> f3 - e3
        1
        >>> Note('a', 8) - Note('c', 4)
        57
        >>> Note('a', 8) - Note('c', '##', 4)
        55
        ```
        
        
        #### <  > operators
        
        
        ```
        >>> f3
        F³
        >>> f3 > e3
        True
        ```
        
        #### != operator
        
        
        ```
        >>> n1 = Note('F', '#', 5)
        >>> n2 = Note('G', 'b', 5)
        >>> n1, n2
        (F♯⁵, G♭⁵)
        >>> n1 != n2
        False
        ```
        
        
        
        
        
        
        Given that python lacks a `===` operator, Notes can be compared for a "stricter" equality using their `is_a()` method:
        
        ```
        >>> n3 == n4
        True
        >>> n3.is_a(n4)
        False
        ```
        
        This method directly compares Note attributes instead of their semitone interval. Set the `ignore_oct` argument appropriately for a less strict comparison:
        
        ```
        >>> n1
        F♯⁵
        >>> n1.is_a(Note('F', '#', 3))
        False
        >>> n1.is_a(Note('F', '#', 3), ignore_oct=False)
        True
        ```
        
        <hr/>
        
        ## kord.keys module:
        
        
        ### class TonalKey(object):
        
        The best way to describe a TonalKey object is basically as a Note object generator. You can use this class to create any theoretical arrangement of musical notes (ie. chords, scales).
        
        Let us take a look at 2 examples using the 2 main categories of child class that inherit from TonalKey class and how they are defined:
        
        
        ### class ChromaticKey(TonalKey):
        
        The ChromaticKey class uses the TonalKey class as an interface while implementing it's own structure of intervals.
        
        ```
        class ChromaticKey(TonalKey):
        
            root_intervals = (
                UNISON,
                MINOR_SECOND,
                MAJOR_SECOND,
                MINOR_THIRD,
                MAJOR_THIRD,
                PERFECT_FOURTH,
                AUGMENTED_FOURTH,
                PERFECT_FIFTH,
                MINOR_SIXTH,
                MAJOR_SIXTH,
                MINOR_SEVENTH,
                MAJOR_SEVENTH,
            )
        ```
        
        We can initialize ChromaticKey objects on any given note and use the ```degree()``` method to obtain one of it's degrees. Using list index notation will achieve a similar result:
        
        ```
        >>> from kord.keys import ChromaticKey
        >>> c_chromatic = ChromaticKey('C')
        >>> c_chromatic.degree(2)
        C♯⁰
        >>> c_chromatic[12]
        B⁰
        ```
        
        Perhaps the most interesting aspect of any TonalKey sub-class is it's ability to iterate over Note objects using one of their several generator methods. As an example, let's take a quick look at the ```scale()``` method:
        
        ```
        >>> for note in c_chromatic.scale()
        ...   print(note, end=' ')
        ...
        C⁰ C♯⁰ D⁰ D♯⁰ E⁰ F⁰ F♯⁰ G⁰ G♯⁰ A⁰ A♯⁰ B⁰ C¹ 
        ```
        
        We can use the ```note_count=``` argument to specify to the scale generator the amount of notes to yield:
        
        ```
        >>> for note in c_chromatic.scale(note_count=4):
        ...   print(note, end=' ')
        ...
        C⁰ C♯⁰ D⁰ D♯⁰ 
        ```
        
        The ```start_note=``` argument can be used to to start yielding from a specific note. This can be done even if the note is not part of the scale:
        
        ```
        >>> from kord.notes import Note
        >>> Ab = Note('A', 'b', 0)
        >>> for note in c_chromatic.scale(note_count=6, start_note=Ab):
        ...   print(note, end=' ')
        ...
        G♯⁰ A⁰ A♯⁰ B⁰ C¹ C♯¹ 
        ```
        
        
        
        ### class DiatonicKey(TonalKey):
        
        ```
        class MajorKey(DiatonicKey):
        
            root_intervals = (
                UNISON,
                MAJOR_SECOND,
                MAJOR_THIRD,
                PERFECT_FOURTH,
                PERFECT_FIFTH,
                MAJOR_SIXTH,
                MAJOR_SEVENTH,
            )
        ```
        
        
        
        ## fretboard sample application
        
        The kord framework comes with a built-in sample application `fretboard.py` that gives some insight into it's possibilities.
        
        ```
        usage: fretboard.py [-h] [-m] [-i] [-t] [-f] [-v] ROOT
        
        <<< Fretboard visualizer sample tool for the kord music framework >>>
        
        positional arguments:
          ROOT                select a root note
        
        optional arguments:
          -h, --help          show this help message and exit
          -m , --mode         music mode to visualize: ['major', 'minor', 'natural_minor', 'melodic_minor', 'harmonic_minor', 'ionian', 'lydian', 'mixo', 'aeolian', 'dorian', 'phrygian', 'chromatic']
          -i , --instrument   instrument fretboard to visualize: ['banjo', 'guitar', 'bass', 'ukulele']
          -t , --tuning       instrument tuning: check your .json files for available options
          -f , --frets        number of displayed frets: [0, 1, 2, .. , 36]
          -v , --verbosity    application verbosity: [0, 1, 2]
        
        ```
        
        I'm pretty sure guitar/bass players may find it very handy as a means to develop their knowledge of their instrument. Have fun!
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Description-Content-Type: text/markdown
