@libraz/libcantus 0.9.5 → 1.0.1

package/README.md

@@ -1,324 +1,115 @@
 # @libraz/libcantus
 
-Pure-TypeScript music theory engine. It takes MIDI note numbers and chord
-symbols and gives back harmonic meaning (Roman numerals, function, cadence,
-key), then generates new parts against that meaning. Built for the tools that
-sit next to a DAW: analyzers, generators, and composition assistants.
-
-It is a theory layer, not an I/O or audio layer. There is no MIDI file reader or
-writer, no audio analysis, and no playback — bring your own parser and hand it
-note events. No runtime dependencies. If you need that other layer as well,
-[libsonare](https://github.com/libraz/libsonare) covers audio analysis,
-mastering, synthesis, and SMF I/O, and its npm binding sits alongside this one;
-the two share no code and neither requires the other.
+Pure-TypeScript music theory for MIDI note events. Build and spell chords, inspect harmony, analyze keys and form, and generate parts from the same data model. The package has no runtime dependencies.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/libraz/libcantus/ci.yml?branch=main&label=CI)](https://github.com/libraz/libcantus/actions)
 [![npm](https://img.shields.io/npm/v/@libraz/libcantus)](https://www.npmjs.com/package/@libraz/libcantus)
 [![codecov](https://codecov.io/gh/libraz/libcantus/branch/main/graph/badge.svg)](https://codecov.io/gh/libraz/libcantus)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/libraz/libcantus/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-22.x-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![docs](https://img.shields.io/badge/docs-API%20reference-b5892e)](https://libraz.github.io/libcantus/)
 
-## What can you do with it?
-
-- **Name and move notes** — parse `C4`, transpose it, convert to/from MIDI, spell
-  intervals with correct enharmonics (`F#` vs `Gb`).
-- **Build chords and progressions** — from scale degrees, Roman numerals
-  (`V7/V`), or lead-sheet symbols (`Cmaj7`, `F#m7b5`, `C/G`).
-- **Analyze harmony** — Roman-numeral analysis, harmonic function, cadence
-  detection, and borrowed / modal-interchange chords.
-- **Recognize chords and keys** — notes in, chord or key out (the inverse of the
-  builders).
-- **Reharmonize** — tritone subs, chromatic mediants, negative harmony, modal
-  interchange palettes.
-- **Voice chords** — smooth 4-voice (SATB) leading, plus drop-2/3, shell, and
-  rootless comping styles.
-- **Generate parts** — bass lines, countermelodies, drums, rhythms, motifs, and
-  whole progressions; deterministic for a given seed.
-- **Analyze a whole arrangement** — feed raw multi-track note events, recover the
-  harmony, get a whole-piece analysis (with per-note conflicts), and generate the
-  missing parts against it.
-- **Work with pitch as sound** — frequencies, cents, EDO, and just intonation.
-
-The theory itself lives in **tree-shakeable pure functions**. On top of them sits
-a **fluent, immutable class API** (`Note`, `Interval`, `Chord`, `Key`,
-`Progression`) that reads like music theory. Which one you get follows a single
-rule: the musical **values** — notes, chords, keys, progressions — have both
-forms and interoperate freely, while operations over **collections and
-timelines** (part generation, whole-arrangement analysis, key ranking) take
-arrays of note events and are exposed as functions only.
+## What it does
 
-## Install
-
-```sh
-yarn add @libraz/libcantus
-```
-
-## Subpath imports
-
-The package root exports everything. To pull in a single layer, import its
-subpath instead:
-
-```ts
-import { Chord, Key, Note } from '@libraz/libcantus/model'; // class API
-import { majorKey, makeChord } from '@libraz/libcantus/theory'; // scales, chords
-import { generateDrums, generateProgression } from '@libraz/libcantus/generate';
-import { analyzeArrangement, detectKey } from '@libraz/libcantus/analyze';
-import { parseNote, edo } from '@libraz/libcantus/core'; // pitch, meter, tuning
-```
-
-The layers are `core`, `theory`, `analyze`, `generate`, and `model`.
-
-## Quick start
-
-The class API chains immutably and carries key context, so analysis needs no
-repetition:
-
-```ts
-import { Chord, Key, Note } from '@libraz/libcantus';
-
-const c = Key.major('C');
-
-c.chord(4, 'dom7').pitchClasses(); // [2, 5, 7, 11]  (G7)
-c.roman('V7/V').voice(); // [ ...SATB MIDI ]  (secondary dominant, voiced)
-Note.of('C4').transpose(7).name; // 'G4'
-
-// A ii–V–I, built and analyzed in one line:
-c.chord(1, 'min').progressionTo(c.chord(4, 'dom7'), c.chord(0, 'maj')).analyze();
-// { chords: [...functional analysis...], cadence: 'authentic' }
-
-Chord.detect([60, 64, 67])[0].quality; // 'maj'
-```
-
-Every class wraps a plain object (`Chord.data`, `Note.data`) and delegates to the
-pure functions, so the two styles interoperate freely. The same task with the
-functional API:
+It sits between software that already holds notes or chord symbols — a DAW project, a MIDI parser, a practice tool — and what those notes mean harmonically. Give it note events and it recovers the harmony; give it that harmony back and it writes parts against it:
 
 ```ts
-import { chordFromDegree, chordPitchClasses, classifyInterval, ConsonanceClass, majorKey } from '@libraz/libcantus';
-
-const cMajor = majorKey(0);
-
-classifyInterval(7); // ConsonanceClass.PerfectConsonance
-chordPitchClasses(chordFromDegree(4, 'dom7', cMajor)); // [2, 5, 7, 11]  (G7)
-```
+import { Composer, Score } from '@libraz/libcantus';
 
-## Name and move notes
+// Four bars of block chords, as a DAW would hand them over:
+const harmony = [[48, 60, 64, 67], [41, 60, 65, 69], [43, 59, 62, 65], [48, 60, 64, 67]].flatMap(
+  (pitches, bar) => pitches.map((pitch) => ({ pitch, startBeat: bar * 4, durationBeat: 4 })),
+);
 
-Parse and format notes, convert to MIDI, and spell intervals so enharmonics the
-pitch-class layer can't tell apart come out right:
+const chords = Score.of(harmony).timeline();
+chords.roman().map((entry) => entry.roman); // ['I', 'IV', 'V7', 'I']
+chords.cadences().at(-1)?.cadence.type; // 'authentic'
 
-```ts
-import { Interval, Note } from '@libraz/libcantus';
-
-Note.of('C4').transpose(7).name; // 'G4'
-Note.of('C4').midi; // 60
-Interval.between(Note.of('C4'), Note.of('F#4')).name; // 'A4'  (augmented fourth)
-Interval.between(Note.of('C4'), Note.of('Gb4')).name; // 'd5'  (diminished fifth)
+// A walking bass over the harmony that was just recovered:
+Composer.of({ key: chords.key, bpm: 120, seed: 1 }).bass(chords, { style: 'walking' }).notes;
+// 16 notes: [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 100 }, ...]
 ```
 
-## Keys and scales
-
-A `KeyScale` is a root pitch class plus a 12-bit `modeMask12` (bit `n` set means
-pitch class `(rootPc + n) % 12` is in the scale). `majorKey`, `minorKey`, and
-`scaleByName` cover the modes, pentatonics, blues, whole-tone, and octatonic
-scales; `MAJOR_MASK` / `NATURAL_MINOR_MASK` let you define custom keys.
-
-`nearestScaleTone` snaps a pitch to the closest in-scale MIDI pitch (preferring
-the lower on a tie) — handy when constraining generated notes to a key.
-
-## Build chords and progressions
+Chord boundaries are searched for rather than assumed, and so is the key, so a piece that modulates is not read against the key it started in.
 
-From scale degrees, Roman numerals, or lead-sheet symbols — and back again:
+What each layer covers:
 
-```ts
-import { Chord, Key } from '@libraz/libcantus';
-
-const c = Key.major('C');
+- **[Pitch and notation](docs/en/pitch-and-notation.md)** — spelled notes and intervals, MIDI conversion, note names read and written in English, German, Japanese, Italian or fixed-do, and line spelling solved as one path instead of note by note. Every text parser has a non-throwing sibling (`tryParseNote`, `tryParseInterval`, `tryParseChordSymbol`, `tryParseKeyName`, `tryParseTimeSignature`, and `tryParse` on `Note`, `Interval`, `Key`, `Chord` and `Meter`), so a text field needs no `try`/`catch` per keystroke.
+- **[Harmony](docs/en/harmony.md)** — chords as structured values, scales including modes, pentatonics and the `WORLD_SCALES` set, Roman numerals and function, voicing, figured bass, and the part-writing and species-counterpoint checkers that report a violation with the voice it happened in and the reason.
+- **[Analysis](docs/en/analysis.md)** — chord and key detection over note events, timelines and cadences, prolongational reduction, phrases, sections, hypermeter, motifs, and arrangement reports.
+- **[Generation](docs/en/generation.md)** — progressions, motifs, rhythms, drums, bass and counter-melody, all drawing on one `GenerationContext`: a project seed, three additive complexity dials (rhythmic, harmonic, ornament), a separate difficulty ceiling, the tempo, and the instrument each part is written for. Same context, same output.
+- **[Time and arrangement](docs/en/time-and-arrangement.md)** — meter, tempo, positions in bars and beats, and analysis across several tracks at once.
+- **[Class API](docs/en/api-reference.md)** — the same theory as one immutable class per thing the library works with, `Score`, `Timeline` and `Composer` included, each a thin skin over the functions above. Reach for a function or a class as it suits the call site; the answers are the same.
 
-c.roman('V7/V').symbol(); // 'D7'  (a secondary dominant)
-c.chord(4, 'dom7').roman(); // 'V7'
-Chord.parse('F#m7b5').pitchClasses(); // [0, 4, 6, 9]
-```
+Answers say why they were reached. `analyzeChord`, `detectCadence` and `explainRoman` carry a `rationale`, `detectKey` attaches one on request, and each can report the readings it turned down as `alternatives`. Where the input cannot settle a question, the field comes back `null` rather than a plausible guess — grading a cadence perfect or imperfect needs a voicing, because only a voicing says what is in the soprano.
 
-Chord vocabulary spans triads through thirteenths — `dim7`, `m7b5`, `minMaj7`,
-`aug7`, sixths, and altered dominants included.
+Spelling is kept wherever it decides the answer. A diminished fifth and an augmented fourth are the same distance in pitch classes but not the same interval, so the counterpoint and part-writing checkers take spelled notes rather than numbers.
 
-Or generate a progression from a style preset (a collection-level operation, so
-it stays functional):
+Seven worked guides start from the data an application already has: [DAW workflow](docs/en/use-cases/daw-workflow.md), [piece analysis](docs/en/use-cases/piece-analysis.md), [modulation report](docs/en/use-cases/modulation-report.md), [harmony exercise checker](docs/en/use-cases/harmony-exercise-checker.md), [generative arrangement](docs/en/use-cases/generative-arrangement.md), [chord chart import](docs/en/use-cases/chord-chart-import.md), and [part preparation](docs/en/use-cases/part-preparation.md).
 
-```ts
-import { generateProgression, majorKey } from '@libraz/libcantus';
+## What it doesn't do
 
-// One chord per bar, secondary dominants inserted where they fit:
-generateProgression({ key: majorKey(0), style: 'idol', bars: 8, reharmonize: true, seed: 1 });
-```
+- **No I/O, notation or audio.** No MIDI file reader or writer, no score rendering, no audio analysis, no playback. Bring your own parser and hand it note events. If that layer is what you need, [libsonare](https://github.com/libraz/libsonare) covers audio analysis, mastering, synthesis and SMF I/O; the two share no code and neither requires the other.
+- **No microtonal analysis.** Frequencies, cents, equal divisions of the octave and just-intonation ratios live in `core`, but everything above the pitch layer runs on twelve pitch classes. Music organised in smaller steps than a semitone is out of reach, which is also why the maqāmāt built on half-flat degrees are left out of `WORLD_SCALES` rather than rounded to a twelve-tone neighbour.
+- **No modal systems.** `WORLD_SCALES` records the pitch material a tradition names — a thāt, a maqām's set, a Japanese pentatonic — and not the system built on it: ascent and descent forms, the notes a phrase leans on, and the phrase grammar have no place in a mask.
+- **No assumption that the material is tonal.** Roman numerals and functional harmony presuppose the common practice, and `supportsFunctionalHarmony` says whether a named scale admits that reading at all — `'dorian'` does, `'miyakoBushi'` does not.
+- **No corpus.** Nothing is bundled to run statistics over.
+- **Known gaps in functional harmony.** `functionOf` answers from a chord and a key alone, so a cadential six-four reads there as an inverted tonic; the dominant reading of it belongs to the layers that see time, and `detectCadence` gives it when the chord before the dominant is passed as `approach`.
 
-## Analyze harmony
+## Requirements
 
-Turn chords into Roman-numeral analysis with function, cadences, and modal
-interchange — in major and minor, respecting inversions:
-
-```ts
-import { Chord, Key } from '@libraz/libcantus';
-
-// A minor iv in a major key reads as a borrowed subdominant:
-Chord.of('F', 'min').analyze(Key.major('C'));
-// { function: 'subdominant', borrowed: true, source: 'parallelMinor', roman: 'iv' }
-```
+Node.js >= 22.
 
-## Recognize chords and keys
-
-Notes in, chord or key out — the inverse of the builders:
-
-```ts
-import { Chord, detectKey } from '@libraz/libcantus';
-
-Chord.detect([60, 64, 67])[0].symbol(); // 'C'
-Chord.detectBest([60, 63, 67, 70])?.symbol(); // 'Cm7'
-detectKey([0, 0, 0, 4, 7])[0]; // C major, best fit  (key ranking stays functional)
-```
-
-## Spell chords and scales
-
-A `Key` carries a spelled tonic, so the pitch-class core produces letter names,
-correct in major and minor:
-
-```ts
-import { Chord, Key } from '@libraz/libcantus';
-
-Key.named('harmonicMinor', 'A').noteNames(); // ['A', 'B', 'C', 'D', 'E', 'F', 'G#']
-Key.minor('E').noteNames(); // ['E', 'F#', 'G', 'A', 'B', 'C', 'D']
-
-// Chords spell in a key's context too:
-Key.major('C').chord(4, 'dom7').spell().map((n) => n.name); // ['G', 'B', 'D', 'F']
-```
-
-## Reharmonize
-
-Reflect a chord through negative harmony on the class, or list substitution
-candidates — tritone, relative, borrowed, and chromatic-mediant subs, plus
-modal-interchange palettes — with the functions:
-
-```ts
-import { Chord, Key, majorKey, parseChordSymbol, substituteChord } from '@libraz/libcantus';
-
-Key.major('C').chord(4, 'dom7').negativeHarmony().symbol(); // 'Dm7b5'
-
-// Substitution/palette search returns lists, so it stays functional:
-substituteChord(parseChordSymbol('G7'), majorKey(0));
-// [{ chord: Db7, type: 'tritone', ... }, ...]
-```
-
-## Choose scales and tensions
-
-Find scales compatible with a chord and its available tensions and avoid notes
-on the class; get a continuity-optimized scale choice across a whole set of
-changes with `scalesForChanges`:
-
-```ts
-import { Chord } from '@libraz/libcantus';
+## Install
 
-Chord.of('C', 'dom7').scales()[0]; // { name: 'mixolydian', rootPc: 0 }
-Chord.of('C', 'maj7').tensions('ionian'); // [2, 9]  (9 and 13; the 11 is an avoid note)
+```sh
+yarn add @libraz/libcantus
 ```
 
-## Voice chords
+## Quick start
 
-Realize a progression into smooth 4-voice (SATB) MIDI voicings with minimal
-motion, or voice a single chord in a comping style (drop-2/3, shell, rootless):
+The theory lives in tree-shakeable pure functions. On top of them sits an immutable class API — one class per thing the library works with, from a single `Note`, `Interval` or `Chord` up to the `Score`, `Timeline`, `Arrangement` and `Composer` that carry a whole piece — that reads the way theory is spoken:
 
 ```ts
 import { Chord, Key } from '@libraz/libcantus';
 
-const c = Key.major('C');
+const key = Key.major('C');
+const dominant = key.chord(5, 'dom7');
 
-// A whole progression, voiced with minimal motion:
-c.chord(0, 'maj').progressionTo(c.chord(5, 'maj'), c.chord(4, 'dom7'), c.chord(0, 'maj')).voice();
-// [[...], [...], [...], [...]]  (one ascending pitch per voice)
-
-// A single chord in a shell comping voicing:
-Chord.of('C', 'maj7').styledVoicing({ style: 'shell' }); // root, third, seventh
+dominant.symbol(); // 'G7'
+dominant.analyze(key).roman; // 'V7'
+Chord.parse('C7(b9,#11)').pitchClasses(); // [0, 1, 4, 6, 7, 10]
 ```
 
-`voiceLeadingCost` and `nextVoicing` let you steer the leading, and the
-`counterpoint` predicates (parallel/hidden perfects, spacing, voice crossing,
-leading-tone resolution, …) let you validate it.
+The functions are the library; every class is a thin skin over them. A class wraps a plain object it exposes as `.data`, and the functions return data a class can be built from, so neither side is a walled garden and the two give the same answers. What a class adds is holding a value together with its context, so a chain of calls does not restate the same facts: a `Score` carries its notes with their meter, tempo, and key, and a `Composer` carries the key, tempo, and seed one piece is written under.
 
-## Generate parts
+## Import paths
 
-Seeded, deterministic generators for melody and accompaniment:
+The package root exports everything. To pull in a single layer, import its subpath instead:
 
 ```ts
-import {
-  generateBassLine, generateCounterMelody, generateDrums, generateRhythm,
-  generateMotif, majorKey, parseTimeSignature,
-} from '@libraz/libcantus';
-
-generateRhythm(parseTimeSignature('4/4'), { seed: 1, density: 0.5 }); // strong-beat-weighted onsets
-const motif = generateMotif({ key: majorKey(0), bars: 2, contour: 'arch', seed: 1 });
-motif.notes.length > 0; // true — a deterministic short melodic cell
-```
-
-`humanize`, `extractGrooveTemplate`, and `applyGrooveTemplate` add a meter-aware
-feel — or capture the feel of one performance and transplant it onto another.
-
-## Analyze and extend an arrangement
-
-The arrangement layer takes raw multi-track `NoteEvent`s — whatever your DAW or
-MIDI-file parser produced — recovers the harmony, then analyses and generates
-against it:
-
-```ts
-import {
-  analyzeArrangement, chordTimelineFromNotes, generateBassLine, generateCounterMelody,
-} from '@libraz/libcantus';
-
-// Infer a chord progression (and the key) from played notes:
-const { timeline, key } = chordTimelineFromNotes(melodyAndChordNotes);
-
-// Whole-piece analysis: inferred chords, cadences, per-note theory labels, and
-// notes that clash with the sounding harmony (with reasons and suggestions):
-const report = analyzeArrangement([
-  { role: 'melody', notes: melodyNotes },
-  { role: 'harmony', notes: chordNotes },
-]);
-report.conflicts; // [{ beat, trackName, pitch, safety, reasons, rationale }, ...]
-
-// Generate the missing parts from the recovered timeline:
-generateBassLine({ segments: timeline.segments, key, style: 'walking', seed: 1 });
-generateCounterMelody({ melody: melodyNotes, timeline, key, register: 'below' });
+import { parseNote, edo } from '@libraz/libcantus/core'; // pitch, meter, tempo, tuning
+import { majorKey, makeChord } from '@libraz/libcantus/theory'; // scales, chords, voicing, rules
+import { analyzeArrangement, detectKey } from '@libraz/libcantus/analyze';
+import { generateDrums, generateProgression } from '@libraz/libcantus/generate';
+import { Chord, Key, Note } from '@libraz/libcantus/model'; // class API
 ```
 
-`harmonizeMelody` goes the other way — given a bare melody, it searches for the
-best key, transpose, and chord path (with optional reharmonization) to harmonize
-it.
+Both ESM and CommonJS builds ship for every path.
 
-Note events shared across the arrangement and generation modules use one type,
-`NoteEvent` (`{ pitch, startBeat, durationBeat, velocity? }`, MIDI pitch in
-quarter-note beats). Seeded generators (`bass`, `groove`, `countermelody`,
-`rhythm`, `drums`, `motif`, `progression`) are deterministic for a given seed.
+## Documentation
 
-## Work with pitch as sound
+Start here: [Introduction](docs/en/introduction.md), [Getting started](docs/en/getting-started.md), [Use cases](docs/en/use-cases/index.md).
 
-Frequencies, cents, EDO, and just intonation — for tuning, microtonality, and
-analysis:
+Domain guides: [Pitch and notation](docs/en/pitch-and-notation.md), [Scales and modes](docs/en/scales-and-modes.md), [Harmony](docs/en/harmony.md), [Key relations and modulation](docs/en/key-relations-and-modulation.md), [Voicing](docs/en/voicing.md), [Counterpoint and part-writing](docs/en/counterpoint-and-part-writing.md), [Time and arrangement](docs/en/time-and-arrangement.md), [Analysis](docs/en/analysis.md), [Melody and motifs](docs/en/melody-and-motifs.md), [Rhythm and groove](docs/en/rhythm-and-groove.md), [Generation](docs/en/generation.md), [Reharmonization](docs/en/reharmonization.md), [Instruments and playability](docs/en/instruments-and-playability.md), [Tuning and frequency](docs/en/tuning-and-frequency.md).
 
-```ts
-import { frequencyOf, edo, justDeviationCents } from '@libraz/libcantus';
-```
+Cross-cutting: [Determinism and seeding](docs/en/determinism-and-seeding.md), [Errors and validation](docs/en/errors-and-validation.md), [Performance](docs/en/performance.md), [Interoperability](docs/en/interoperability.md).
 
-Meter helpers (`TimeSignature`, `parseTimeSignature`, `beatsPerBar`,
-`metricWeight`, `isStrongBeat`, `tuplet`) cover simple and compound meters and
-back the accent-aware generators.
-
-## Documentation
+Reference: [API reference](docs/en/api-reference.md), [Glossary](docs/en/glossary.md), [Questions and limitations](docs/en/faq.md).
 
-Full API reference — every export with signatures, categorized by domain and
-with runnable examples — is generated from the source and published at
-**[libraz.github.io/libcantus](https://libraz.github.io/libcantus/)**.
+Every `ts` example in these guides is executed by the test suite, and an expected value written as a trailing comment is checked against what the call returns. The generated TypeDoc reference is written to `docs/api` and is separate from the hand-authored guides.
 
 ## License
 
-Apache-2.0
+[@libraz/libcantus](https://github.com/libraz/libcantus) is released under the [Apache License 2.0](LICENSE).