@hiyve/react-music-theory

React hooks and components for music theory drills: a note, an interval, a chord, a key signature or a scale on the staff to name — or heard first and named by ear — the answers to choose from — or the answer played on an instrument — the question played once answered, and the score at the end. The questions come from @hiyve/music-theory; the staff is engraved by the notation engine you supply, as with @hiyve/react-music-notation.

Installation

npm install @hiyve/react-music-theory @hiyve/music-theory @hiyve/react-music-notation
Copy

Peer dependencies: react, react-dom, @mui/material, @mui/icons-material, @emotion/react, @emotion/styled.

Quick start

import { useState } from 'react';
import { defaultTheoryDrillSettings, generateTheoryQuestion, newSeed } from '@hiyve/music-theory';
import { useDrill, DrillCard, DrillScoreCard, TheoryDrillPanel } from '@hiyve/react-music-theory';

const loadEngine = () => import('opensheetmusicdisplay');

function TheoryDrill() {
  const [settings, setSettings] = useState(defaultTheoryDrillSettings);
  const [length, setLength] = useState(10);
  const [seed, setSeed] = useState(() => newSeed());
  const drill = useDrill({ generate: (random) => generateTheoryQuestion(settings, random), length, seed });
  return (
    <>
      <TheoryDrillPanel settings={settings} onChange={setSettings} length={length} onLengthChange={setLength} onStart={() => setSeed(newSeed())} locked={!drill.finished && drill.summary.answered > 0} />
      {drill.round ? (
        <DrillCard round={drill.round} index={drill.index} total={drill.total} summary={drill.summary} loadEngine={loadEngine} onAnswer={drill.answer} onNext={drill.next} />
      ) : (
        <DrillScoreCard summary={drill.summary} onAgain={() => drill.restart()} onAnother={() => setSeed(newSeed())} />
      )}
    </>
  );
}
Copy

A drill is drawn from its seed, so "Try the same one again" asks the same questions and a new seed asks new ones. Each question is played as an answer is chosen — a chord at once, a melodic interval or a scale note by note — so it is heard as well as seen, and the card keeps the score as the drill goes. Answers show by name: "Major 3rd", "Half-diminished 7th", "Dorian", "E♭ major".

By ear

Turn on the panel's By ear switch — or set byEar: true in a drill's settings — and every question of notes, intervals, chords and scales is heard before it is seen. DrillCard plays it as it appears, with the staff hidden and a button to hear it again; a note is played after a C, to name it from ("First you hear C, then the question"). Key signatures are read — there is nothing in a signature to hear — so the switch is not offered for them. Once answered, the staff shows and the question plays again, each note lit as it sounds. No two answers offered sound alike, so F♯ and G♭, or an augmented 4th and a diminished 5th, are never both there.

The first question plays as the card appears, after the click that started the drill; if the browser keeps the sound from starting, the "Hear it again" button plays it.

Answered by playing

Turn on the panel's Play the answer switch — or set playAnswer: true in a drill's settings, for any kind — and each question is answered on an instrument instead of by choosing. DrillCard says what to play ("Play or sing this note. Then the Major 3rd above it.", "Play the Minor chord in first inversion, with this note at the bottom."), shows and sounds the note to start from — a note to read and play is shown alone, giving nothing away — and once answered shows the notes to play marked as a graded take's are — each coloured by how it was played, with the note played in a wrong one's place drawn beside it. With By ear on too, the question is heard and played back.

The listening itself is PlayDrillCard, from @hiyve/react-music-performance/theory: it hears the playing through the microphone or a MIDI instrument, with the same note following as a practice take, and judges it note by note. A card of your own can listen any other way through DrillCard's answerArea, noteStyles and onSoundingChange; without an answerArea, a question set to be played is answered by choosing, like any other.

Hooks

Components

TheoryDrillGuide

<TheoryDrillPanel settings={settings} onChange={setSettings} length={length} onLengthChange={setLength} onStart={start} />
{!started && <TheoryDrillGuide settings={settings} onStart={start} />}
Copy

The default words are short and plain, for anyone new to music: "Two notes. How far apart are they?", "Play or sing your answer." drillHint(settings, labels) is the one line the panel and the guide both show for what an exercise asks.

TheoryDrillPanel

Each drill's options: notes — on the staff or out to the ledger lines, sharps and flats; intervals — which intervals, together or one note after the other, sharps and flats; chords — which qualities, inversions, sharps and flats; key signatures — up to how many sharps or flats, major or minor keys or both; scales — which scales, sharps and flats. For intervals, chords and scales, "sharps and flats" lets the notes they are built on be sharps and flats too. A list always keeps at least one entry.

DrillCard

DrillScoreCard

drillPraise(accuracy, labels) and drillTone(accuracy, colors) give the word and the colour a score earns.

StaffSnippet

AnswerChoices

Piano sound

By default the notes play on a small built-in voice that needs no download. To hear a real piano, give DrillCard (or useNoteSynth) a sample host laid out like the midi-js-soundfonts collection:

const PIANO = { baseUrl: 'https://cdn.example.com/soundfonts/FluidR3_GM/' };
<DrillCard samples={PIANO} … />
Copy

The SDK ships no samples: you choose the host, and that set's licence applies — FluidR3_GM, for one, is Creative Commons Attribution 3.0 and asks to be credited, while 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. Each note is about 25 KB and is downloaded once, while its question is on screen. A note that cannot be fetched in time plays on the built-in voice, so a note always sounds. The layout and the SampleSource fields are described in the @hiyve/music-theory README.

Names

Answers are codes (M3, halfDiminished7, dorian, D:major); the components show them by name. defaultTheoryNames holds the English names — intervals, chords and scales by code, and keyMajor / keyMinor templates with {tonic} — and names overrides any of them, name by name:

<DrillCard names={{ intervals: { P8: 'Perfect 8th' }, keyMinor: '{tonic}m' }} … />
Copy

Notes are named by their letters ("F♯"). names.note names them another way, such as solfège, wherever a note is named: in the answers, the key names, the note to start from, and the questions missed:

const SOLFEGE: Record<string, string> = { C: 'Do', D: 'Re', E: 'Mi', F: 'Fa', G: 'Sol', A: 'La', B: 'Si' };
<DrillCard names={{ note: (name) => SOLFEGE[name[0]] + name.slice(1) }} … />
Copy

For views of your own:

• answerLabel(kind, answer, names) gives the name of any answer.
• noteLabel(pitch, names, octave?) gives a note's name.
• questionNotesText(question, names?) gives the notes behind a question ("C4 E4", "D F A").
• mergeTheoryNames(overrides?) fills in the rest.

Customization

Every component takes labels. The drill components also take colors, as MUI palette paths or CSS colours:

• right, wrong, good, fair, poor
• playing: a note on the staff while it sounds
• staff: behind the staff, which is drawn in black (default white)

The text on a right or wrong answer is picked to read on its colour. The defaults are exported (defaultDrillCardLabels, defaultTheoryDrillPanelLabels, defaultDrillColors, …) with merge functions (mergeDrillCardLabels, mergeTheoryDrillPanelLabels, mergeTheoryDrillGuideLabels, mergeDrillColors, …). withClef(settings, clef), withByEar(settings, byEar), withPlayAnswer(settings, playAnswer), noteIdRangeOf(settings) and withNoteIdRange(settings, clef, range) are the helpers behind the panel's clef, by-ear, play and range choices.

Requirements

• React 18 or 19, and MUI 9.
• A notation engine, supplied through loadEngine, as for @hiyve/react-music-notation's player. The public opensheetmusicdisplay build is enough: the drills only draw, and play their notes with their own voice.
• Sound needs Web Audio; browsers start it only after a user gesture — choosing an answer is one, and so is the click that starts a drill, for a question asked by ear.
• With samples, the sample host must allow your page to fetch from it (CORS) and be allowed by your connect-src.