birdears package

birdears provides facilities to building musical ear training exercises.

birdears.CHROMATIC_FLAT = ('C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B')

Chromatic notes names using flats.

A mapping of the chromatic note names using flats.

Type

tuple

birdears.CHROMATIC_SHARP = ('C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B')

Chromatic notes names using sharps.

A mapping of the chromatic note namesu sing sharps

Type

tuple

birdears.CHROMATIC_TYPE = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)

A map of the chromatic scale.

A map of the the semitones which compound the chromatic scale.

Type

tuple

birdears.CIRCLE_OF_FIFTHS = [('C', 'G', 'D', 'A', 'E', 'B', 'Gb', 'Db', 'Ab', 'Eb', 'Bb', 'F'), ('C', 'F', 'Bb', 'Eb', 'Ab', 'C#', 'F#', 'B', 'E', 'A', 'D', 'G')]

Circle of fifths.

These are the circle of fifth in both directions.

Type

list of tuples

birdears.D(data, nlines=0)

birdears.DEGREE_INDEX = {'i': [0], 'ii': [1, 2], 'iii': [3, 4], 'iv': [5, 6], 'v': [6, 7], 'vi': [8, 9], 'vii': [10, 11], 'viii': [12]}

A mapping of semitones of each degree.

A mapping of semitones which index to each degree roman numeral, major/minor, perfect, augmented/diminished

Type

dict of lists

birdears.DIATONIC_MASK = {'dorian': (1, 0, 1, 1, 0, 1, 0, 1, 0, 1, 1, 0), 'locrian': (1, 1, 0, 1, 0, 1, 1, 0, 1, 0, 1, 0), 'lydian': (1, 0, 1, 0, 1, 0, 1, 1, 0, 1, 0, 1), 'major': (1, 0, 1, 0, 1, 1, 0, 1, 0, 1, 0, 1), 'minor': (1, 0, 1, 1, 0, 1, 0, 1, 1, 0, 1, 0), 'mixolydian': (1, 0, 1, 0, 1, 1, 0, 1, 0, 1, 1, 0), 'phrygian': (1, 1, 0, 1, 0, 1, 0, 1, 1, 0, 1, 0)}

A map of the diatonic scale.

A mapping of the semitones which compound each of the greek modes.

Type

dict of tuples

birdears.INTERVALS = ((0, 'P1', 'Perfect Unison'), (1, 'm2', 'Minor Second'), (2, 'M2', 'Major Second'), (3, 'm3', 'Minor Third'), (4, 'M3', 'Major Third'), (5, 'P4', 'Perfect Fourth'), (6, 'A4', 'Augmented Fourth'), (7, 'P5', 'Perfect Fifth'), (8, 'm6', 'Minor Sixth'), (9, 'M6', 'Major Sixth'), (10, 'm7', 'Minor Seventh'), (11, 'M7', 'Major Seventh'), (12, 'P8', 'Perfect Octave'), (13, 'A8', 'Minor Ninth'), (14, 'M9', 'Major Ninth'), (15, 'm10', 'Minor Tenth'), (16, 'M10', 'Major Tenth'), (17, 'P11', 'Perfect Eleventh'), (18, 'A11', 'Augmented Eleventh'), (19, 'P12', 'Perfect Twelfth'), (20, 'm13', 'Minor Thirteenth'), (21, 'M13', 'Major Thirteenth'), (22, 'm14', 'Minor Fourteenth'), (23, 'M14', 'Major Fourteenth'), (24, 'P15', 'Perfect Double-octave'), (25, 'A15', 'Minor Sixteenth'), (26, 'M16', 'Major Sixteenth'), (27, 'm17', 'Minor Seventeenth'), (28, 'M17', 'Major Seventeenth'), (29, 'P18', 'Perfect Eighteenth'), (30, 'A18', 'Augmented Eighteenth'), (31, 'P19', 'Perfect Nineteenth'), (32, 'm20', 'Minor Twentieth'), (33, 'M20', 'Major Twentieth'), (34, 'm21', 'Minor Twenty-first'), (35, 'M21', 'Major Twenty-first'), (36, 'P22', 'Perfect Triple-octave'))

Data representing intervals.

A tuple of tuples representing data for the intervals with format (semitones, short name, full name).

Type

tuple of tuples

birdears.INTERVAL_INDEX = {1: [0], 2: [1, 2], 3: [3, 4], 4: [5, 6], 5: [6, 7], 6: [8, 9], 7: [10, 11], 8: [12]}

A mapping of semitones of each interval.

A mapping of semitones which index to each interval name, major/minor, perfect, augmented/diminished

Type

dict of lists

birdears.KEYS = ('C', 'C#', 'Db', 'D', 'D#', 'Eb', 'E', 'F', 'F#', 'Gb', 'G', 'G#', 'Ab', 'A', 'A#', 'Bb', 'B')

Allowed keys

These are the allowed keys for exercise as comprehended by birdears.

Type

tuple

Subpackages

• birdears.interfaces package
  • Submodules
  • birdears.interfaces.commandline module
    • CommandLine
      • CommandLine.process_key()
    • center_text()
    • make_input_str()
    • print_instrumental()
    • print_question()
    • print_response()
  • birdears.interfaces.urwid module
    • Keyboard
      • Keyboard.highlight_key()
    • KeyboardButton
      • KeyboardButton.highlight()
    • Pad()
    • QuestionWidget
      • QuestionWidget.draw_display()
      • QuestionWidget.redraw_display()
    • TextUserInterface
      • TextUserInterface.check_question()
      • TextUserInterface.create_question()
      • TextUserInterface.draw_question()
      • TextUserInterface.keypress()
      • TextUserInterface.run_question()
      • TextUserInterface.update_input_display()
      • TextUserInterface.update_question_display()
    • TextUserInterfaceWidget
    • is_chromatic()
• birdears.questions package
  • Submodules
  • birdears.questions.harmonicinterval module
    • HarmonicIntervalQuestion
      • HarmonicIntervalQuestion.check_question()
      • HarmonicIntervalQuestion.make_pre_question()
      • HarmonicIntervalQuestion.make_question()
      • HarmonicIntervalQuestion.make_resolution()
      • HarmonicIntervalQuestion.name
      • HarmonicIntervalQuestion.play_question()
      • HarmonicIntervalQuestion.play_resolution()
  • birdears.questions.instrumentaldictation module
    • InstrumentalDictationQuestion
      • InstrumentalDictationQuestion.check_question()
      • InstrumentalDictationQuestion.make_pre_question()
      • InstrumentalDictationQuestion.make_question()
      • InstrumentalDictationQuestion.make_resolution()
      • InstrumentalDictationQuestion.name
      • InstrumentalDictationQuestion.play_question()
  • birdears.questions.melodicdictation module
    • MelodicDictationQuestion
      • MelodicDictationQuestion.check_question()
      • MelodicDictationQuestion.make_pre_question()
      • MelodicDictationQuestion.make_question()
      • MelodicDictationQuestion.make_resolution()
      • MelodicDictationQuestion.name
      • MelodicDictationQuestion.play_question()
      • MelodicDictationQuestion.play_resolution()
  • birdears.questions.melodicinterval module
    • MelodicIntervalQuestion
      • MelodicIntervalQuestion.check_question()
      • MelodicIntervalQuestion.make_pre_question()
      • MelodicIntervalQuestion.make_question()
      • MelodicIntervalQuestion.make_resolution()
      • MelodicIntervalQuestion.name
      • MelodicIntervalQuestion.play_question()
      • MelodicIntervalQuestion.play_resolution()
  • birdears.questions.notename module
    • NoteNameQuestion
      • NoteNameQuestion.check_question()
      • NoteNameQuestion.make_pre_question()
      • NoteNameQuestion.make_question()
      • NoteNameQuestion.make_resolution()
      • NoteNameQuestion.name
      • NoteNameQuestion.play_question()
      • NoteNameQuestion.play_resolution()

Submodules

birdears.exception module

exception birdears.exception.InvalidNote

Bases: Exception

exception birdears.exception.InvalidOctave

Bases: Exception

exception birdears.exception.InvalidPitch

Bases: Exception

exception birdears.exception.InvalidSequenceElement

Bases: Exception

birdears.interval module

class birdears.interval.Interval(pitch_a, pitch_b)

Bases: dict

This class represents the interval between two pitches..

tonic_octave

Scientific octave for the tonic. For example, if the tonic is a ‘C4’ then tonic_octave is 4.

Type

int

interval octave

Scientific octave for the interval. For example, if the interval is a ‘G5’ then tonic_octave is 5.

Type

int

chromatic_offset

The offset in semitones inside one octave. Relative semitones to tonic.

Type

int

note_and_octave

Note and octave of the interval, for example, if the interval is G5 the note name is ‘G5’.

Type

str

note_name

The note name of the interval, for example, if the interval is G5 then the name is ‘G’.

Type

str

semitones

Semitones from tonic to octave. If tonic is C4 and interval is G5 the number of semitones is 19.

Type

int

is_chromatic

If the current interval is chromatic (True) or if it exists in the diatonic scale which key is tonic.

Type

bool

is_descending

If the interval has a descending direction, ie., has a lower pitch than the tonic.

Type

bool

diatonic_index

If the interval is chromatic, this will be the nearest diatonic interval in the direction of the resolution (closest tonic.) From II to IV degrees, it is the ditonic interval before; from V to VII it is the diatonic interval after.

Type

int

distance

A dictionary which the distance from tonic to interval, for example, if tonic is C4 and interval is G5:

{
    'octaves': 1,
    'semitones': 7
}

Type

dict

data

A tuple representing the interval data in the form of (semitones, short_name, long_name), for example:

(19, 'P12', 'Perfect Twelfth')

Type

tuple

birdears.interval.get_interval_by_semitones(semitones)

birdears.logger module

This submodule exports logger to log events.

Logging messages which are less severe than lvl will be ignored:

Level       Numeric value
-----       -------------
CRITICAL    50
ERROR       40
WARNING     30
INFO        20
DEBUG       10
NOTSET      0

Level       When it’s used
-----       --------------
DEBUG       Detailed information, typically of interest only when
                diagnosing problems.
INFO        Confirmation that things are working as expected.
WARNING     An indication that something unexpected happened, or indicative
                of some problem in the near future (e.g. ‘disk space low’).
                The software is still working as expected.
ERROR       Due to a more serious problem, the software has not been able
                to perform some function.
CRITICAL    A serious error, indicating that the program itself may be
                unable to continue running.

birdears.logger.log_event(f, *args, **kwargs)

Decorator. Functions and method decorated with this decorator will have their signature logged when birdears is executed with –debug mode. Both function signature with their call values and their return will be logged.

birdears.note_and_pitch module

class birdears.note_and_pitch.Chord(iterable)

Bases: list

append(obj)

Append object to the end of the list.

delay = None

duration = None

extend(iterable)

Extend list by appending elements from the iterable.

class birdears.note_and_pitch.Note(note='C', accident='sharp')

Bases: object

property pitch_class

class birdears.note_and_pitch.Pitch(note='C', octave=4, accident='sharp')

Bases: Note

delay = None

distance(other)

duration = None

property pitch_number

birdears.note_and_pitch.get_abs_chromatic_offset(pitch1, pitch2)

birdears.note_and_pitch.get_pitch_by_number(numeric, accident='sharp')

birdears.note_and_pitch.get_pitch_class(note)

birdears.note_and_pitch.get_pitch_number(note, octave)

birdears.prequestion module

This module implements pre-questions’ progressions.

Pre questions are chord progressions or notes played before the question is played, so to affirmate the sound of the question’s key.

For example a common cadence is chords I-IV-V-I from the diatonic scale, which in a key of C is CM-FM-GM-CM and in a key of A is AM-DM-EM-AM.

Pre-question methods should be decorated with register_prequestion_method decorator, so that they will be registered as a valid pre-question method.

class birdears.prequestion.PreQuestion(method, question)

Bases: object

birdears.prequestion.none(question, *args, **kwargs)

Pre-question method that return an empty sequence with no delay. :param question: Question object from which to generate the

pre-question sequence. (this is provided by the Resolution class when it is `__call__`ed)

birdears.prequestion.progression_i_iv_v_i(question, *args, **kwargs)

Pre-question method that play’s a chord progression with triad chords built on the grades I, IV, V the I of the question key.

Parameters

question (obj) – Question object from which to generate the pre-question sequence. (this is provided by the Resolution class when it is `__call__`ed)

birdears.prequestion.register_prequestion_method(f, *args, **kwargs)

Decorator for prequestion method functions.

Functions decorated with this decorator will be registered in the PREQUESTION_METHODS global dict.

birdears.prequestion.tonic_only(question, *args, **kwargs)

Pre-question method that only play’s the question tonic note before the question.

Parameters

question (object) – Question object from which to generate the pre-question sequence. (this is provided by the Resolution class when it is `__call__`ed)

birdears.questionbase module

class birdears.questionbase.QuestionBase(mode='major', tonic='C', octave=4, descending=False, chromatic=False, n_octaves=1, valid_intervals=(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11), user_durations=None, prequestion_method=None, resolution_method=None, default_durations=None, *args, **kwargs)

Bases: object

Base Class to be subclassed for Question classes.

This class implements attributes and routines to be used in Question subclasses.

check_question()

This method should be overwritten by the question subclasses.

make_question()

This method should be overwritten by the question subclasses.

make_resolution()

This method should be overwritten by the question subclasses.

play_question()

This method should be overwritten by the question subclasses.

birdears.questionbase.get_valid_pitches(scale, valid_intervals=(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11))

birdears.questionbase.register_question_class(cls, *args, **kwargs)

Decorator for question classes.

Classes decorated with this decorator will be registered in the QUESTION_CLASSES global.

birdears.resolution module

class birdears.resolution.Resolution(method, question)

Bases: object

This class implements methods for different types of question resolutions.

A resolution is an answer to a question. It aims to create a mnemonic on how the inverval resolves to the tonic.

birdears.resolution.nearest_tonic(question)

Resolution method that resolve the intervals to their nearest tonics.

Parameters

question (obj) – Question object from which to generate the resolution sequence. (this is provided by the Prequestion class when it is `__call__`ed)

birdears.resolution.register_resolution_method(f, *args, **kwargs)

Decorator for resolution method functions.

Functions decorated with this decorator will be registered in the RESOLUTION_METHODS global dict.

birdears.resolution.repeat_only(question)

Resolution method that only repeats the sequence elements with given durations.

Parameters

question (obj) – Question object from which to generate the resolution sequence. (this is provided by the Prequestion class when it is `__call__`ed)

birdears.scale module

class birdears.scale.ChromaticScale(tonic='C', octave=4, n_octaves=1, descending=False, dont_repeat_tonic=False)

Bases: ScaleBase

Builds a musical chromatic scale.

scale

The array of notes representing the scale.

Type

array_type

get_triad(mode, index=0, degree=None)

Returns an array with notes from a scale’s triad.

Parameters

• mode (str) – Mode of the scale (eg. ‘major’ or ‘minor’)

• index (int) – Triad index (eg.: 0 for 1st degree triad.)

• degree (int) – Degree of the scale. If provided, overrides the index argument. (eg.: 1 for the 1st degree triad.)

Returns

A list with three pitches (str), one for each note of the triad.

class birdears.scale.DiatonicScale(tonic='C', mode='major', octave=4, n_octaves=1, descending=False, dont_repeat_tonic=False)

Bases: ScaleBase

Builds a musical diatonic scale.

scale

The array of notes representing the scale.

Type

array_type

get_triad(index=0, degree=None)

Returns an array with notes from a scale’s triad.

Parameters

• index (int) – triad index (eg.: 0 for 1st degree triad.)

• degree (int) – Degree of the scale. If provided, overrides the index argument. (eg.: 1 for the 1st degree triad.)

Returns

An array with three pitches, one for each note of the triad.

class birdears.scale.ScaleBase

Bases: list

birdears.sequence module

class birdears.sequence.Sequence(elements=[], duration=2, delay=1.5, pos_delay=1)

Bases: list

Register a Sequence of notes and/or chords.

elements

List of notes (strings) ou chords (list of strings) in this Sequence.

Type

array_type

async_play(callback, end_callback, args, kwargs)

Plays the Sequence elements of notes and/or chords and wait for Sequence.pos_delay seconds.

make_chord_progression(tonic_pitch, mode, degrees)

Appends triad chord(s) to the Sequence.

Parameters

• tonic (str) – Tonic note of the scale.

• mode (str) – Mode of the scale from which build the triads upon.

• degrees (array_type) – List with integers represending the degrees of each triad.

play(callback=None, end_callback=None, *args, **kwargs)

birdears.utils module

class birdears.utils.DictCallback(other=None, **kwargs)

Bases: dict

callback = None

callback_args = []

callback_kwargs = {}

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]