Alto
dev

alto.exercises.library

The exercises: note names, intervals, key signatures, scales, chords, arpeggios, keyboard keys and note construction.

Each class makes one kind of Question and registers itself with @register, so importing this module is what adds the exercises to the home screen.

Examples

>>> from alto.exercises import REGISTRY
>>> [cls.name for cls in REGISTRY][:3]
['Note Identification', 'Keyboard Note Identification', 'Note Construction']

NoteNames

NoteNames(accidentals: bool = False)

Bases: ChoiceExercise

Name the note shown on a staff.

Examples

>>> q = NoteNames().generate(random.Random(1))
>>> len(q.staff), q.answer in q.choices
(1, True)

Constructor

Create the exercise.

Parameters

  • accidentals (bool, default False): Ask notes with explicit sharps, flats and naturals, whatever the settings say.

Constructor examples

>>> NoteNames(accidentals=True).accidentals
True

NoteNames.practice_signature

def practice_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, ranges, key signatures, note values and naming in force, and whether accidentals are asked.

Examples

>>> NoteNames().settings_signature() != NoteNames(accidentals=True).settings_signature()
True

NoteNames.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "Press the button with its name" in NoteNames().instructions()
True

NoteNames.make_question

def make_question(rng: random.Random) -> Question

Make a note to name, on one of the chosen clefs, in a chosen key.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The note drawn on a staff, with one button for each name that could be the answer.

Examples

>>> q = NoteNames().generate(random.Random(2))
>>> q.clef in ("treble", "bass", "alto", "tenor", "soprano", "mezzo", "baritone", "grand")
True

NoteNames.card_count

def card_count() -> int

Count written pitches across the selected ranges, clefs and signatures.

Returns

  • int: Each staff position contributes one spelling, or three when accidentals are enabled.

Examples

>>> NoteNames().card_count() > 0
True

NoteNames.daily_candidates

def daily_candidates(rng: random.Random) -> Iterator[Question]

Visit each selectable written note once, in shuffled order.

Parameters

  • rng (random.Random): Source of the daily order and answer choices.

Yields

  • Question: A distinct question within the selected clefs, ranges and keys.

Examples

>>> isinstance(next(NoteNames().daily_candidates(random.Random(0))), Question)
True

NoteNames.review_question

def review_question(
    question: Question,
    *,
    same_settings: bool,
) -> Question | None

Rebuild a previously seen note when its pitch and answer are eligible.

Parameters

  • question (Question): Saved note and answer.
  • same_settings (bool): Whether its original settings are active.

Returns

  • Question or None: The note with the current answer bank, or None outside the selected material.

Examples

>>> ex = NoteNames()
>>> q = ex.generate(random.Random(1))
>>> ex.review_question(q, same_settings=True) == q
True

IntervalNames

class IntervalNames(Exercise)

Name the interval between two written notes.

Examples

>>> q = IntervalNames().generate(random.Random(3))
>>> [len(chord) for chord in q.staff], q.answer in q.choices
([2], True)

IntervalNames.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "quality followed by a number" in IntervalNames().instructions()
True

IntervalNames.settings_signature

def settings_signature() -> str

Identify the settings used to generate and grade the interval.

Returns

  • str: The stored-question review signature.

Examples

>>> "Harmonic" in IntervalNames().settings_signature()
True

IntervalNames.refresh

def refresh(question: Question) -> Question

Arrange written interval answers by quality, with interval numbers in columns.

Parameters

  • question (Question): A new or saved interval question.

Returns

  • Question: The same answer choices in reading order. Perfect and major share a row.

Examples

>>> q = Question("", choices=["d3", "m3", "P4", "M3", "A3"], answer="m3")
>>> IntervalNames().refresh(q).choices
['A3', 'M3', 'P4', 'm3', 'd3']

IntervalNames.generate

def generate(rng: random.Random) -> Question

Make two notes whose interval is to be named.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The lower and higher note on a staff, and the interval (such as ‘M3’ or ‘P5’) as the answer.

Examples

>>> q = IntervalNames().generate(random.Random(4))
>>> q.answer[0] in "PMmAd" and q.answer[1:].isdigit()
True

KeyboardIntervals

class KeyboardIntervals(Exercise)

Identify the ascending interval between two highlighted piano keys.

Attributes

  • INTERVALS (tuple of str): Conventional names for every distance on the piano, including compound intervals and combined tritone answers.

Examples

>>> q = KeyboardIntervals().generate(random.Random(5))
>>> len(q.keyboard_notes), q.answer in q.choices, q.staff
(2, True, [])

KeyboardIntervals.settings_signature

def settings_signature() -> str

Identify the keyboard range and selected intervals for stored-question reviews.

Returns

  • str: The settings that determine which questions can be asked.

Examples

>>> bool(KeyboardIntervals().settings_signature())
True

KeyboardIntervals.instructions

def instructions() -> str

Explain how to identify an interval from two highlighted keys.

Returns

  • str: HTML explaining interval names and enharmonic ambiguity on the keyboard.

Examples

>>> "A4 / d5" in KeyboardIntervals().instructions()
True

KeyboardIntervals.generate

def generate(rng: random.Random) -> Question

Highlight two distinct keys at a selected interval within the chosen range.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: Two highlighted keys and either a limited number of choices or a fixed bank for every selected interval. A prompt is returned if none are selected.

Examples

>>> q = KeyboardIntervals().generate(random.Random(7))
>>> 1 <= q.keyboard_notes[1].midi - q.keyboard_notes[0].midi <= 12
True

KeySignatures

class KeySignatures(ChoiceExercise)

Read a key signature drawn on a staff and name the key it belongs to.

Examples

>>> q = KeySignatures().generate(random.Random(5))
>>> q.answer in q.choices
True

KeySignatures.practice_signature

def practice_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The kinds of question, clefs, scales and key signatures in force.

Examples

>>> KeySignatures().settings_signature().startswith("[")
True

KeySignatures.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "Key Signature Identification" in KeySignatures().instructions()
True

KeySignatures.refresh

def refresh(question: Question) -> Question

Give a stored signature question the caption on its staff that older versions did not write.

Parameters

  • question (Question): The question as it was stored.

Returns

  • Question: The same question, captioned ‘_ Major’ (or ‘_ minor’, ‘_ Dorian’ and so on) if it shows a staff and had no caption.

Examples

>>> old = Question("Which minor key has this key signature?", choices=["C"], answer="C", key=-3, show_staff=True)
>>> KeySignatures().refresh(old).caption
'_ minor'

KeySignatures.make_question

def make_question(rng: random.Random) -> Question

Make a key signature to read.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A signature on a staff; the answer is the tonic of the scale that has it.

Examples

>>> q = KeySignatures().generate(random.Random(6))
>>> q.show_staff and q.answer in q.choices
True

KeySignatureConstruction

class KeySignatureConstruction(Exercise)

Build the key signature of a named key on a blank staff, with the fork.

Examples

>>> q = KeySignatureConstruction().generate(random.Random(5))
>>> q.build_key, q.staff, q.choices
(True, [], [])

KeySignatureConstruction.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, scales and key signatures in force.

Examples

>>> KeySignatureConstruction().settings_signature().startswith("[")
True

KeySignatureConstruction.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "Key Signature Construction" in KeySignatureConstruction().instructions()
True

KeySignatureConstruction.generate

def generate(rng: random.Random) -> Question

Name a key whose signature is to be built.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A blank staff captioned with the key, such as ‘D Major’; the answer is its sharps or flats.

Examples

>>> q = KeySignatureConstruction().generate(random.Random(1))
>>> q.caption.split()[0] in {"C", "D", "E", "F", "G", "A", "B"} or "♯" in q.caption or "♭" in q.caption
True
>>> q.answer == format_key_signature(q.key)
True

OrderOfKeys

class OrderOfKeys(Exercise)

Write the accidentals of a named key signature in order.

Examples

>>> OrderOfKeys().generate(random.Random(1)).place_signature
True

OrderOfKeys.settings_signature

def settings_signature() -> str

Identify the selections used to generate a practice question.

Returns

  • str: The original empty signature at the defaults, so earlier questions remain available for review.

Examples

>>> OrderOfKeys().settings_signature()
''

OrderOfKeys.instructions

def instructions() -> str

Explain how to enter and submit a signature.

Returns

  • str: The exercise help text.

Examples

>>> "Undo" in OrderOfKeys().instructions()
True

OrderOfKeys.generate

def generate(rng: random.Random) -> Question

Choose a key from the selected scales and signatures and spell it in a selected clef.

Parameters

  • rng (random.Random): Source for the key, mode, and clef.

Returns

  • Question: The named key and the ordered signs with their exact staff octaves.

Examples

>>> q = OrderOfKeys().generate(random.Random(2))
>>> q.show_staff and not q.choices
True

ScaleIdentification

class ScaleIdentification(Exercise)

Identify the tonic and type of a scale drawn on a staff.

Examples

>>> q = ScaleIdentification().generate(random.Random(7))
>>> len(q.staff), q.answer in q.choices
(8, True)

ScaleIdentification.settings_signature

def settings_signature() -> str

Identify the clefs, scale types and staff and scale signatures in force.

Returns

  • str: The serialized question settings.

Examples

>>> ScaleIdentification().settings_signature().startswith("[")
True

ScaleIdentification.instructions

def instructions() -> str

Explain how to identify the scale, including a staff with a different signature.

Returns

  • str: Simple HTML help text.

Examples

>>> "Scale Identification" in ScaleIdentification().instructions()
True

ScaleIdentification.generate

def generate(rng: random.Random) -> Question

Draw a one-octave scale and offer scale names without revealing the answer on the staff.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: Eight staff notes and a choice of tonic and scale type.

Examples

>>> q = ScaleIdentification().generate(random.Random(8))
>>> q.staff[0][0].name == q.staff[-1][0].name and not q.caption
True

ScaleConstruction

class ScaleConstruction(Exercise)

Place the notes of a named scale on a blank staff, one after another.

Examples

>>> q = ScaleConstruction().generate(random.Random(5))
>>> len(q.construct_scale or []), q.choices, q.key
(8, [], 0)

ScaleConstruction.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, scales and key signatures in force.

Examples

>>> ScaleConstruction().settings_signature().startswith("[")
True

ScaleConstruction.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "Scale Construction" in ScaleConstruction().instructions()
True

ScaleConstruction.generate

def generate(rng: random.Random) -> Question

Name a scale to be placed on the staff.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A blank staff captioned with the scale, such as ‘D Major’. The eight notes in the selected direction are stored in construct_scale.

Examples

>>> q = ScaleConstruction().generate(random.Random(1))
>>> scale = q.construct_scale or []
>>> scale[0].name == scale[-1].name and q.accidentals
True
>>> q.check_scale(scale)
True

CircleOfFifths

class CircleOfFifths(ChoiceExercise)

Questions on the circle of fifths: a relative major, a relative minor, or the Roman numeral of a chord.

Examples

>>> q = CircleOfFifths().generate(random.Random(3))
>>> q.circle is not None and q.answer in q.choices
True

CircleOfFifths.practice_signature

def practice_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The kinds of question in force.

Examples

>>> CircleOfFifths().settings_signature().startswith("[")
True

CircleOfFifths.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML, with a paragraph for each kind of question that is switched on.

Examples

>>> "circle of fifths" in CircleOfFifths().instructions()
True

CircleOfFifths.make_question

def make_question(rng: random.Random) -> Question

Pick a kind of question that is switched on, and ask it.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A question on the circle: circle_kind says which kind.

Examples

>>> settings.circle.questions = {"minor"}
>>> q = CircleOfFifths().generate(random.Random(5))
>>> q.circle_kind, q.prompt
('minor', 'Which minor key is the relative minor of F major?')
>>> settings.circle.questions = set(settings.CIRCLE_QUESTIONS)

ChordQualities

class ChordQualities(ChoiceExercise)

Identify the quality of a triad or seventh chord in root position.

Examples

>>> q = ChordQualities().generate(random.Random(9))
>>> len(q.staff[0]) in (3, 4) and q.answer in q.choices
True

ChordQualities.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "root position" in ChordQualities().instructions()
True

ChordQualities.make_question

def make_question(rng: random.Random) -> Question

Make a chord in root position whose quality is to be named.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The chord drawn as one stack of notes, with its type (such as ‘minor 7th’) as the answer.

Examples

>>> q = ChordQualities().generate(random.Random(10))
>>> q.answer in CHORDS
True

ArpeggioNames

class ArpeggioNames(ChoiceExercise)

Name the type and the inversion of a broken chord.

Examples

>>> q = ArpeggioNames().generate(random.Random(11))
>>> q.octaves is not None and len(q.staff) >= 4
True

ArpeggioNames.practice_signature

def practice_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, chord types, inversions and key signatures in force.

Examples

>>> ArpeggioNames().settings_signature().startswith("[")
True

ArpeggioNames.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "inversion" in ArpeggioNames().instructions()
True

ArpeggioNames.make_question

def make_question(rng: random.Random) -> Question

Make an arpeggio on one of the chosen clefs, in a chosen position.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The arpeggio’s notes one after another on a staff; the answer is the chord type and inversion, such as ‘major · 1st inversion’.

Raises

  • RuntimeError: If no arpeggio fits the chosen clefs, chord types and inversions.

Examples

>>> q = ArpeggioNames().generate(random.Random(12))
>>> " · " in q.answer
True

KeyboardNotes

class KeyboardNotes(ChoiceExercise)

Name the highlighted key on a piano keyboard.

Examples

>>> q = KeyboardNotes().generate(random.Random(13))
>>> q.keyboard is not None and q.answer in q.choices
True

KeyboardNotes.practice_signature

def practice_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The keyboard range, black keys, octave and key signature settings, and the naming in force.

Examples

>>> KeyboardNotes().settings_signature().startswith("[")
True

KeyboardNotes.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML, with paragraphs added for the octave and key signature settings that are on.

Examples

>>> "highlighted" in KeyboardNotes().instructions()
True

KeyboardNotes.make_question

def make_question(rng: random.Random) -> Question

Make a keyboard with one key highlighted.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The keyboard, a grid of name buttons (and a row of octave buttons if octaves are asked), and the key’s name as the answer, with the other spelling of a black key accepted.

Examples

>>> q = KeyboardNotes().generate(random.Random(14))
>>> # noinspection PyUnresolvedReferences
>>> q.keyboard_range[0] <= q.keyboard.midi <= q.keyboard_range[1]
True

NoteConstruction

class NoteConstruction(Exercise)

Place a named note on the staff.

Examples

>>> q = NoteConstruction().generate(random.Random(15))
>>> q.construct is not None and q.prompt.startswith("Place ")
True

NoteConstruction.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, accidentals and key signature settings, and the naming in force.

Examples

>>> NoteConstruction().settings_signature().startswith("[")
True

NoteConstruction.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML, with paragraphs added for the key signature and accidental settings that are on.

Examples

>>> "Click the staff" in NoteConstruction().instructions()
True

NoteConstruction.generate

def generate(rng: random.Random) -> Question

Make a note name to be placed on the staff.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A prompt such as ‘Place F♯4 on the staff.’; the answer is the note’s name, and construct is the note to place.

Examples

>>> q = NoteConstruction().generate(random.Random(16))
>>> q.answer in q.prompt
True

NoteConstruction.card_count

def card_count() -> int

Count distinct construction cards without rendering them.

Returns

  • int: Number of eligible written placements under the current settings.

Examples

>>> NoteConstruction().card_count() > 0
True

NoteConstruction.daily_candidates

def daily_candidates(rng: random.Random) -> Iterator[Question]

Visit all eligible placements in a randomized order.

Parameters

  • rng (random.Random): Source for the order of the signatures and placements.

Yields

  • Question: One playable placement for each combination.

Examples

>>> next(NoteConstruction().daily_candidates(random.Random(5))).construct is not None
True

NoteConstruction.review_question

def review_question(
    question: Question,
    *,
    same_settings: bool,
) -> Question | None

Determine whether an introduced placement belongs to the current construction catalog.

Parameters

  • question (Question): Stored construction card.
  • same_settings (bool): Whether its original settings are still active.

Returns

  • Question or None: The playable card if its placement and prompt remain eligible.

Examples

>>> ex = NoteConstruction()
>>> q = ex.generate(random.Random(3))
>>> ex.review_question(q, same_settings=True) == q
True

ClefBasics

class ClefBasics(ChoiceExercise)

Put a named clef on a blank staff: choose the G, C or F symbol and put it on the line that makes the clef asked for.

Examples

>>> q = ClefBasics().generate(random.Random(1))
>>> q.answer == q.place_clef and q.place_clef in settings.CLEF_BASICS_CLEFS
True

ClefBasics.settings_signature

def settings_signature() -> str

Use button preferences for reviews only when the learner answers with buttons.

Returns

  • str: The signature for the active question type.

Examples

Changing Button count leaves staff-placement reviews available.

ClefBasics.practice_signature

def practice_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs asked for.

Examples

>>> ClefBasics().settings_signature().startswith("[")
True

ClefBasics.instructions

def instructions() -> str

Return the help text for the exercise, for the kind of question that is being asked.

Returns

  • str: Simple HTML.

Examples

>>> "Clef Basics" in ClefBasics().instructions()
True

ClefBasics.make_question

def make_question(rng: random.Random) -> Question

Name a clef to place, or draw a clef to name.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: For construction, a blank staff and the name of the clef, which is the question written under the staff. For identification, a staff with the clef drawn on it, and a button for each clef that can be asked for.

Examples

>>> q = ClefBasics().generate(random.Random(3))
>>> q.prompt.startswith("Place the ") and q.caption == q.prompt
True
>>> settings.clef_basics.question_type = "identification"
>>> q = ClefBasics().generate(random.Random(3))
>>> q.answer in q.choices, q.place_clef, q.caption
(True, '', 'Which clef is this?')
>>> settings.clef_basics.question_type = "construction"

NotationIdentification

class NotationIdentification(ChoiceExercise)

Identify the highlighted part of a written phrase.

Examples

>>> q = NotationIdentification().generate(random.Random(2))
>>> bool(q.staff or q.notation_excerpt) and q.answer in q.choices
True

NotationIdentification.settings_signature

def settings_signature() -> str

Use button preferences for reviews only when the learner answers with buttons.

Returns

  • str: The signature for the active question type.

Examples

Changing Button count leaves staff-placement reviews available.

NotationIdentification.practice_signature

def practice_signature() -> str

Identify the terms eligible for review.

Returns

  • str: The selected terms, or the original empty signature when all terms are enabled.

Examples

>>> NotationIdentification().settings_signature()
''

NotationIdentification.instructions

def instructions() -> str

Explain how to answer the notation question.

Returns

  • str: Help for mouse and keyboard users.

Examples

>>> "number" in NotationIdentification().instructions()
True

NotationIdentification.refresh

def refresh(question: Question) -> Question

Replace unchecked distractors in older practice questions before replay.

Parameters

  • question (Question): Stored question matching the current settings signature.

Returns

  • Question: The original notation with eligible answer buttons.

Examples

>>> ex = NotationIdentification()
>>> q = ex.generate(random.Random(1))
>>> ex.refresh(q) == q
True

NotationIdentification.make_question

def make_question(rng: random.Random) -> Question

Choose a phrase and a single visible feature to highlight.

Parameters

  • rng (random.Random): Source for the phrase, feature, and its position.

Returns

  • Question: A short phrase with the selected marking and checked answer choices.

Examples

>>> q = NotationIdentification().generate(random.Random(0))
>>> q.notation_target[0] == q.answer
True

NotationIdentification.card_groups

def card_groups() -> dict[str, str]

Group the active question type’s playable examples by the symbol being practiced.

Returns

  • dict of str to str: Map from each eligible example’s item key to its selected term.

Examples

>>> bool(NotationIdentification().card_groups())
True

NotationIdentification.daily_candidates

def daily_candidates(rng: random.Random) -> Iterator[Question]

Choose one example for each selected notation term.

Parameters

  • rng (random.Random): Randomizes term order, examples and distractors.

Yields

  • Question: A distinct playable card with the current answer controls.

Examples

>>> next(NotationIdentification().daily_candidates(random.Random(4))).answer in settings.notation.terms
True

NotationIdentification.review_question

def review_question(
    question: Question,
    *,
    same_settings: bool,
) -> Question | None

Recover an eligible saved example under the current term and button selections.

Parameters

  • question (Question): Saved question.
  • same_settings (bool): Whether the presentation settings still match.

Returns

  • Question or None: The current presentation of the card, or None if its term or example is outside the catalog.

Examples

>>> ex = NotationIdentification()
>>> q = ex.generate(random.Random(4))
>>> ex.review_question(q, same_settings=True) == q
True