Music
Music theory facade — constants, conversions, interval generation, and shruti alignment.
What is MusicTheory?
The shared utility layer for pitch ↔ MIDI ↔ note-label ↔ cents conversions, note-name constants (Western, Carnatic, Hindustani), and interval generation (12-TET and Just Intonation). Also provides alignShruti for computing a student's practice tonic relative to a lesson key.
Used as a building block across the SDK: Accura for intonation analysis, PitchAnalysis for histogram computation, and demo apps for pitch visualization.
When to Use
| Scenario | Method(s) | Why |
|---|---|---|
| Convert Hz ↔ MIDI ↔ note label | hzToMidi, midiToHz, hzToNoteLabel, etc. | Core pitch-space conversions |
| Get cents deviation from nearest note | centsDeviation | Tuner-style display |
| Generate target intervals for a scale | generateEqTemperedIntervals, generateJustIntonationIntervals | Feed to PitchAnalysis.quantize or Accura.analyzePitching |
| Compute a student's practice shruti | alignShruti | Shruti picker UI + CalibraLiveEval.setStudentKeyHz |
Quick Start
Kotlin
val midi = MusicTheory.hzToMidi(440f) // 69.0
val hz = MusicTheory.midiToHz(69f) // 440.0
val label = MusicTheory.hzToNoteLabel(440f) // "A4"
val cents = MusicTheory.hzToCents(466.16f, tonicHz = 440f) // ~100
val intervals = MusicTheory.EQ_TEMPERED_INTERVALS_CENTS_BASE // [0, 100, ..., 1100]Swift
let midi = MusicTheory.hzToMidi(440.0) // 69.0
let hz = MusicTheory.midiToHz(69.0) // 440.0
let label = MusicTheory.hzToNoteLabel(440.0) // "A4"
let cents = MusicTheory.hzToCents(466.16, tonicHz: 440.0) // ~100
let names = MusicTheory.noteNames // ["C", "C#", "D", ...]Common Pitfalls
hzToCentsdefault tonic is A4 (440 Hz): If you're working relative to a different tonic (e.g., the singer's shruti), pass it explicitly.Note labels use sharps only:
midiToNoteLabelreturns"C#4", never"Db4".noteLabelToMidiaccepts both sharps and flats.centsDeviationrange is -50 to +50: It reports deviation from the nearest 12-TET note, not from a custom tonic.
See also
Uses MusicTheory for intonation analysis
Uses MusicTheory for histogram computation
Result of alignShruti
Properties
Reference pitch for A4 (Hz).
MIDI note number for A4.
Number of cents in an octave.
Number of cents in a semitone (in 12-TET).
Default maximum cents for interval lists.
Default minimum cents for interval lists.
12-TET intervals spanning multiple octaves.
Base 12-TET intervals in cents within one octave (0 to 1100).
JI intervals spanning multiple octaves.
Base JI intervals in cents within one octave.
Standard chromatic note names using sharps for accidentals.
Standard Carnatic swarasthana names (12 pitch classes).
Standard Hindustani sargam note names (12 notes per octave).
Maps note names (e.g., "C", "C#", "Db") to their base MIDI number within an octave (0-11).
Number of semitones in an octave (12-tone equal temperament).
Functions
Compute the practice shruti (tonic) for a student given their natural shruti and the reference lesson key.
Get cents deviation from nearest note (-50 to +50).
Convert cents to MIDI note number.
Convert cents to note label (relative to tonic).
Compute the user's practice shruti from their natural speaking pitch (NSP) and most-recent vocal range, applying the policy from Musicmuni research synthesis (§B7).
Convert frequency in Hz to note label.
Convert MIDI note number to cents.
Convert MIDI note number to note label (e.g., "A4", "C#5").
Convert note label to cents (relative to tonic).
Convert note label to frequency in Hz.
Convert note label to MIDI note number.
Convert a frequency ratio to cents.