@hiyve/music-theory

Framework-agnostic music theory drills: questions to order — a note, an interval, a chord, a key signature or a scale on a staff to name, or heard first and named by ear, with the answers to choose from — or to play on an instrument — as plain data and MusicXML, seeded drills that ask them round by round, and a small sound engine to hear them. Works in any framework; @hiyve/react-music-theory is the React layer with the staff, the answer buttons and the score card.

Installation

npm install @hiyve/music-theory
Copy

Quick start

import { defaultTheoryDrillSettings, generateTheoryQuestion, startDrill, answerDrill, nextQuestion, drillSummary } from '@hiyve/music-theory';

// Ten intervals on the treble staff, four answers to choose from each time.
const settings = { ...defaultTheoryDrillSettings, kind: 'interval' as const };
let drill = startDrill((random) => generateTheoryQuestion(settings, random), { length: 10, seed: 42 });

const { question } = drill.rounds[drill.index];
question.musicxml; // a one-bar score with the question on its staff — draw it with any MusicXML renderer
question.choices;  // ['M3', 'P5', 'm3', 'P4'] — shuffled, the right one among them
question.notes;    // the notes behind it, spelled: C4 and E4
question.sounds;   // what it sounds like, as MIDI numbers: [60, 64]

drill = answerDrill(drill, 'M3', 1800); // judged against question.answer; the time is optional
drill = nextQuestion(drill);

drillSummary(drill); // { total, answered, correct, accuracy, meanElapsedMs, missed }
Copy

The same seed makes the same drill again, so a drill can be kept, shared or retried by its seed.

Questions

Every question has its kind, clef, answer, shuffled choices (the answer among them), the musicxml to draw, the notes it is made of, the sounds to play and whether they are heard together or inOrder (playback), whether it is asked by ear (byEar) and, if so, the reference note to name it from, and whether it is answered by playing (playAnswer) and, if so, what to play (play). Notes are always spelled by letter — a major third above E is G♯, never A♭ — and a question that would need a double sharp or flat is never asked.

random is the drill's source (createRandom(seed)); startDrill passes it. Each function throws when its settings leave nothing to ask — an interval too wide for the range, no mode chosen.

With both major and minor keys asked, a key signature's relative key — the other key it could equally be — is never offered against the right answer.

By ear

Notes, intervals, chords and scales can be asked by ear: set byEar: true in the kind's settings, and the question is meant to be heard before it is seen. Key signatures are always read — there is nothing in a signature to hear — so their settings have no byEar.

const q = generateNoteQuestion({ byEar: true, accidentals: true }, random);
q.byEar;     // true
q.reference; // the C at or below the note, to play first: name the note from it
q.sounds;    // then the note itself
Copy

• A note comes with a reference: the C at or below it. Play it first, then the note, and the note is named from it. An interval, a chord or a scale is named from its own notes, so its reference is null.
• No two answers offered sound alike, since the ear cannot tell them apart: never F♯ with G♭, or an augmented 4th with a diminished 5th. Each sound keeps one name among the choices.
• A question asked by sight has byEar: false and no reference. Asking by ear changes nothing about drills asked by sight: the same seed asks the same questions as before.

Answered by playing

Any kind can be answered on an instrument instead of by name: set playAnswer: true in its settings, and the question says what to play in play (PlayTask).

play.playback says whether the notes are played together or inOrder; play.musicxml is the notes to play as a one-bar score — to follow the playing against and to show once answered — and play.promptMusicxml what the staff shows before: the note given, or the note to read. Asked by ear as well, nothing is given or shown (start and promptMusicxml are null): the question is heard and played back. Judge the playing however suits — @hiyve/react-music-performance/theory does it from a microphone or a MIDI instrument — and record it with answerDrill(drill, played, elapsedMs, correct), where correct is how it went.

Settings

TheoryDrillSettings holds the settings of every kind and the kind asked, so a page can switch drills and find each as it was left (defaultTheoryDrillSettings).

Every kind is asked by sight unless byEar is set — a key signature always is — and answered by name unless playAnswer is set. The answers offered are drawn from the kind's own list — the intervals, qualities or scales chosen — so fewer are offered when fewer are chosen. accidentals lets a question start on a sharp or a flat.

Building blocks

Drills

Sound

import { NoteSynth } from '@hiyve/music-theory';

// Make the context from a user gesture. Without `samples`, a built-in voice plays.
const synth = new NoteSynth(new AudioContext(), {
  samples: { baseUrl: 'https://cdn.example.com/soundfonts/FluidR3_GM/' }, // a piano
});
synth.play(60);                  // middle C, for 900 ms
synth.play([60, 64, 67]);        // a chord
synth.playInOrder([60, 64], 500); // a melodic interval, half a second apart

// A question, as it is meant to be heard.
question.playback === 'inOrder' ? synth.playInOrder(question.sounds) : synth.play(question.sounds);

// Told as each note starts and stops sounding, by its place in the list — to light it on the staff.
const stop = synth.playInOrder(question.sounds, 500, undefined, {
  onNoteStart: (index) => console.log('sounding', question.notes[index]),
  onNoteEnd: (index) => console.log('done', question.notes[index]),
});
Copy

Instrument samples

The SDK ships no samples: you choose the host, and that set's licence applies. samples (SampleSource) points at a host laid out like the midi-js-soundfonts collection, with one file per key:

{baseUrl}{instrument}-{format}/{note}.{format}     e.g. …/FluidR3_GM/acoustic_grand_piano-mp3/Db4.mp3
Copy

Black keys are written as flats (Db4). A key outside the range, a file that cannot be fetched, or a sample still downloading after sampleWaitMs (1200 ms) is played with the built-in voice instead, so a note always sounds. The FluidR3_GM set, for one, is released under Creative Commons Attribution 3.0 and asks to be credited; the University of Iowa Electronic Music Studios piano recordings may be used for any project without restrictions, once trimmed, encoded and hosted in this layout yourself. The host must allow your page to fetch from it (CORS) and be allowed by your connect-src.

Pitches

Defaults

defaultTheoryDrillSettings and the settings of each kind, each with its merge function, which spreads the defaults first and the overrides after:

Also exported:

• the lists intervalNames, chordQualities and scaleTypes
• clefRanges: each clef's staff, and out to its second ledger line either side, as MIDI numbers

At least two answers are always offered, whatever choiceCount asks for. melodicMinor is the ascending form of the melodic minor scale, with the raised sixth and seventh.

Requirements

• No runtime dependencies. ESM and CommonJS builds.
• NoteSynth needs Web Audio (a browser); everything else runs anywhere.