@libraz/libcantus 0.9.4 → 1.0.0

package/README.md

@@ -1,315 +1,115 @@
 # @libraz/libcantus
 
-Pure-TypeScript toolkit for working with music: name notes and chords, analyze
-harmony, recognize what you're hearing, voice and reharmonize progressions, and
-generate parts (bass, countermelody, drums, rhythm) — all with no runtime
-dependencies.
+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 what you hear** — 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.
-- **Arrange from a DAW / MIDI file** — feed raw multi-track notes, 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 musical **values** — notes, chords, keys, progressions — come in two
-interchangeable styles: a **fluent, immutable class API** (`Note`, `Chord`,
-`Key`, `Progression`) that reads like music theory, and the underlying
-**tree-shakeable pure functions**. Operations over **collections and timelines**
-(part generation and whole-arrangement analysis) work on arrays of note events,
-so — like `rhythm`, `drums`, and `detectKey` — they are exposed as functions.
+## 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, majorKey } from '@libraz/libcantus';
-
-const cMajor = majorKey(0);
-
-classifyInterval(7); // IntervalQuality.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 what you hear
-
-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.
-
-## Arrange from a DAW or MIDI file
-
-The arrangement layer takes raw multi-track `NoteEvent`s, 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).

package/README_ja.md

@@ -0,0 +1,115 @@
+# @libraz/libcantus
+
+MIDI ノートイベントを扱う、TypeScript 製の音楽理論ライブラリです。コードの組み立てと綴り、和声とキーの解析、曲の形式の読み取り、パート生成を同じデータモデルで行えます。実行時依存はありません。
+
+[![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-%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/)
+
+## できること
+
+すでにノートやコード記号を持っているソフトウェア（DAW のプロジェクト、MIDI パーサー、練習支援ツールなど）と、その音が和声的に何を意味するかとの間を埋めます。ノートイベントを渡せば和声が求まり、その和声を渡せばそれに沿ったパートが書けます。
+
+```ts
+import { Composer, Score } from '@libraz/libcantus';
+
+// DAW から渡ってくる形の、4 小節のブロックコード:
+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 })),
+);
+
+const chords = Score.of(harmony).timeline();
+chords.roman().map((entry) => entry.roman); // ['I', 'IV', 'V7', 'I']
+chords.cadences().at(-1)?.cadence.type; // 'authentic'
+
+// 求まった和声の上に、ウォーキングベースを書く:
+Composer.of({ key: chords.key, bpm: 120, seed: 1 }).bass(chords, { style: 'walking' }).notes;
+// 16 音: [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 100 }, ...]
+```
+
+コードの境界は決め打ちせずに探索し、キーも同様に探します。転調する曲を、冒頭のキーのまま読み続けることはありません。
+
+各レイヤーが受け持つ範囲は次のとおりです。
+
+- **[音高と記譜](docs/ja/pitch-and-notation.md)** — 綴りを保った音名と音程、MIDI 変換、英語・ドイツ語・日本語・イタリア語・固定ドでの読み書き、そして 1 音ずつではなく声部全体を 1 本の経路として解く綴り付け。テキストのパーサーにはいずれも例外を投げない対 (`tryParseNote`、`tryParseInterval`、`tryParseChordSymbol`、`tryParseKeyName`、`tryParseTimeSignature`、および `Note`・`Interval`・`Key`・`Chord`・`Meter` の `tryParse`) があるので、入力欄の 1 打鍵ごとに `try`/`catch` を書く必要はありません。
+- **[和声](docs/ja/harmony.md)** — 構造を持つ値としてのコード、教会旋法やペンタトニックに加えて `WORLD_SCALES` を含むスケール、ローマ数字と和声機能、ヴォイシング、数字付き低音、そして違反した声部と理由まで返す声部書法・種目対位法のチェッカー。
+- **[解析](docs/ja/analysis.md)** — ノートイベントからのコード・キー検出、タイムラインとカデンツ、和声的な還元、フレーズ、セクション、ハイパーメーター、モチーフ、アレンジ全体のレポート。
+- **[生成](docs/ja/generation.md)** — プログレッション、モチーフ、リズム、ドラム、ベース、対旋律。いずれも 1 つの `GenerationContext` を参照します。プロジェクトのシード、加算的な 3 つの複雑さのダイヤル（リズム・和声・装飾）、それとは別枠の難易度の上限、テンポ、各パートの対象楽器がそこに入ります。同じコンテキストからは同じ結果が出ます。
+- **[時間とアレンジ](docs/ja/time-and-arrangement.md)** — 拍子、テンポ、小節と拍による位置、複数トラックをまたぐ解析。
+- **[クラス API](docs/ja/api-reference.md)** — 同じ理論を、ライブラリが扱う対象ごとの不変クラスとして提供します。`Score`、`Timeline`、`Composer` も含め、いずれも上記の関数の薄い外皮です。呼び出し側の都合で関数とクラスのどちらを使ってもよく、返る答えは同じです。
+
+答えには、そう読んだ理由が付きます。`analyzeChord`、`detectCadence`、`explainRoman` は `rationale` を必ず返し、`detectKey` は要求があれば付けます。いずれも、退けた解釈を `alternatives` として報告できます。渡された情報だけでは決まらない場合、それらしい答えを作らずに `null` を返します。カデンツが完全か不完全かはヴォイシングがなければ決まりません。ソプラノに何があるかはヴォイシングだけが答えられるからです。
+
+答えを左右する場面では、綴りの情報を落としません。減 5 度と増 4 度はピッチクラス上の距離が同じでも同じ音程ではないので、声部書法と対位法のチェッカーは数値ではなく綴られた音を受け取ります。
+
+アプリケーションが手元に持っているデータから始まるガイドが 7 本あります。[DAW との連携](docs/ja/use-cases/daw-workflow.md)、[曲の解析](docs/ja/use-cases/piece-analysis.md)、[転調レポート](docs/ja/use-cases/modulation-report.md)、[和声課題のチェック](docs/ja/use-cases/harmony-exercise-checker.md)、[生成によるアレンジ](docs/ja/use-cases/generative-arrangement.md)、[コード譜の取り込み](docs/ja/use-cases/chord-chart-import.md)、[パートの準備](docs/ja/use-cases/part-preparation.md)です。
+
+## やらないこと
+
+- **入出力・記譜・音声を扱いません。** MIDI ファイルの読み書き、楽譜の描画、音声解析、再生はありません。パーサーは各自で用意し、ノートイベントとして渡してください。その層こそが必要なら、[libsonare](https://github.com/libraz/libsonare) が音声解析、マスタリング、合成、SMF 入出力を扱います。両者はコードを共有せず、どちらも相手を必要としません。
+- **微分音の解析はしません。** 周波数、セント、オクターブの等分割、純正律の比は `core` にありますが、音高より上の層はすべて 12 のピッチクラスで動きます。半音より細かい単位で組み立てられた音楽は範囲外です。半フラットの音度を持つマカームを 12 音の近い音で代用せず `WORLD_SCALES` から外しているのも、同じ理由です。
+- **旋法体系そのものは扱いません。** `WORLD_SCALES` が収録するのは、thāt やマカーム、日本の音階といった伝統が名を与えた音組織であって、その上に立つ体系ではありません。上行形と下行形、フレーズが寄りかかる音、旋律型の文法は、マスクには入りません。
+- **調性を前提にしません。** ローマ数字と機能和声は西洋の慣習を前提とします。その読み方が適用できるスケールかどうかは `supportsFunctionalHarmony` が答えます（`'dorian'` は真、`'miyakoBushi'` は偽）。
+- **コーパスは持ちません。** 統計を取るためのデータは同梱していません。
+- **機能和声には既知の穴があります。** `functionOf` は和音と調だけから答えるため、終止四六の和音はその層では主和音の転回として読まれます。属和音としての読みは時間軸を見る層のものであり、属和音の前の和音を `approach` として渡したときに `detectCadence` がそれを示します。
+
+## 要件
+
+Node.js >= 22。
+
+## インストール
+
+```sh
+yarn add @libraz/libcantus
+```
+
+## 最初の例
+
+理論の本体はツリーシェイク可能な純粋関数にあります。その上に、理論を語るときの言い方に近い不変のクラス API が乗っています。ライブラリが扱う対象ごとに1つのクラスがあり、単体の `Note`、`Interval`、`Chord` から、曲全体を受け持つ `Score`、`Timeline`、`Arrangement`、`Composer` までが揃います。
+
+```ts
+import { Chord, Key } from '@libraz/libcantus';
+
+const key = Key.major('C');
+const dominant = key.chord(5, 'dom7');
+
+dominant.symbol(); // 'G7'
+dominant.analyze(key).roman; // 'V7'
+Chord.parse('C7(b9,#11)').pitchClasses(); // [0, 1, 4, 6, 7, 10]
+```
+
+本体は関数で、クラスはいずれもその薄い外皮です。クラスは `.data` でプレーンな値を公開し、関数が返したデータからクラスを作れます。どちらかが閉じた世界になることはなく、返す答えも同じです。クラスが足すのは、値とその文脈をひとまとめに保持することです。呼び出しを連ねるときに同じ事実を書き直さずに済みます。`Score` は音符と拍子・テンポ・調をまとめて持ち、`Composer` は 1 曲を書くときの調・テンポ・シードを持ちます。
+
+## インポートパス
+
+ルートからすべてを export しています。1 つのレイヤーだけを取り込みたい場合は、サブパスを使ってください。
+
+```ts
+import { parseNote, edo } from '@libraz/libcantus/core'; // 音高、拍子、テンポ、音律
+import { majorKey, makeChord } from '@libraz/libcantus/theory'; // スケール、コード、ヴォイシング、規則
+import { analyzeArrangement, detectKey } from '@libraz/libcantus/analyze';
+import { generateDrums, generateProgression } from '@libraz/libcantus/generate';
+import { Chord, Key, Note } from '@libraz/libcantus/model'; // クラス API
+```
+
+いずれのパスにも ESM と CommonJS の両方のビルドがあります。
+
+## ドキュメント
+
+最初に読むページ: [概要](docs/ja/introduction.md)、[使い始める](docs/ja/getting-started.md)、[ユースケース](docs/ja/use-cases/index.md)。
+
+各領域のガイド: [音高と記譜](docs/ja/pitch-and-notation.md)、[スケールとモード](docs/ja/scales-and-modes.md)、[和声](docs/ja/harmony.md)、[調関係と転調](docs/ja/key-relations-and-modulation.md)、[ボイシング](docs/ja/voicing.md)、[対位法と和声課題](docs/ja/counterpoint-and-part-writing.md)、[時間とアレンジ](docs/ja/time-and-arrangement.md)、[解析](docs/ja/analysis.md)、[旋律とモチーフ](docs/ja/melody-and-motifs.md)、[リズムとグルーヴ](docs/ja/rhythm-and-groove.md)、[生成](docs/ja/generation.md)、[リハーモナイズ](docs/ja/reharmonization.md)、[楽器と演奏可能性](docs/ja/instruments-and-playability.md)、[音律と周波数](docs/ja/tuning-and-frequency.md)。
+
+横断的な話題: [決定性とシード](docs/ja/determinism-and-seeding.md)、[エラーと検証](docs/ja/errors-and-validation.md)、[パフォーマンス](docs/ja/performance.md)、[相互運用](docs/ja/interoperability.md)。
+
+リファレンス: [API リファレンス](docs/ja/api-reference.md)、[用語集](docs/ja/glossary.md)、[FAQ と制限](docs/ja/faq.md)。
+
+これらのガイドの `ts` の例はすべてテストスイートで実行され、末尾コメントに書いた期待値は実際の返り値と照合されます。生成される TypeDoc のリファレンスは `docs/api` に出力され、手書きガイドとは分かれています。
+
+## ライセンス
+
+[@libraz/libcantus](https://github.com/libraz/libcantus) は [Apache License 2.0](LICENSE) で提供します。

package/dist/analyze/index.cjs

@@ -1,5 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
+var _chunkMXO72PLYcjs = require('../chunk-MXO72PLY.cjs');
 
 
 
@@ -7,8 +8,6 @@
 
 
 
-var _chunkRC6GBMCDcjs = require('../chunk-RC6GBMCD.cjs');
-require('../chunk-36N73KZ3.cjs');
 
 
 
@@ -26,12 +25,9 @@ require('../chunk-36N73KZ3.cjs');
 
 
 
-var _chunkCAN76NCUcjs = require('../chunk-CAN76NCU.cjs');
+var _chunk3JXCW6DXcjs = require('../chunk-3JXCW6DX.cjs');
 
 
-var _chunkQ6OP4U43cjs = require('../chunk-Q6OP4U43.cjs');
-require('../chunk-FNDWXRRI.cjs');
-require('../chunk-7MGZ7D62.cjs');
 
 
 
@@ -54,9 +50,60 @@ require('../chunk-7MGZ7D62.cjs');
 
 
 
+var _chunkOE6WK2Y2cjs = require('../chunk-OE6WK2Y2.cjs');
+require('../chunk-K4ZJUGF4.cjs');
 
 
+var _chunkUADYAYATcjs = require('../chunk-UADYAYAT.cjs');
+require('../chunk-Q2WGKJNN.cjs');
 
 
-exports.NoteSafety = _chunkQ6OP4U43cjs.NoteSafety; exports.analyzeArrangement = _chunkRC6GBMCDcjs.analyzeArrangement; exports.analyzeChord = _chunkCAN76NCUcjs.analyzeChord; exports.analyzeVoice = _chunkRC6GBMCDcjs.analyzeVoice; exports.borrowedSource = _chunkCAN76NCUcjs.borrowedSource; exports.chordTimelineFromChords = _chunkRC6GBMCDcjs.chordTimelineFromChords; exports.chordTimelineFromNotes = _chunkRC6GBMCDcjs.chordTimelineFromNotes; exports.chordToRoman = _chunkCAN76NCUcjs.chordToRoman; exports.detectCadence = _chunkCAN76NCUcjs.detectCadence; exports.detectCadences = _chunkRC6GBMCDcjs.detectCadences; exports.detectChord = _chunkCAN76NCUcjs.detectChord; exports.detectChordBest = _chunkCAN76NCUcjs.detectChordBest; exports.detectKey = _chunkCAN76NCUcjs.detectKey; exports.detectKeyBest = _chunkCAN76NCUcjs.detectKeyBest; exports.detectKeyFromNotes = _chunkCAN76NCUcjs.detectKeyFromNotes; exports.functionOf = _chunkCAN76NCUcjs.functionOf; exports.isBorrowedChord = _chunkCAN76NCUcjs.isBorrowedChord; exports.isDiatonic = _chunkCAN76NCUcjs.isDiatonic; exports.isMinorKey = _chunkCAN76NCUcjs.isMinorKey; exports.parallelKey = _chunkCAN76NCUcjs.parallelKey; exports.romanToChord = _chunkCAN76NCUcjs.romanToChord; exports.secondaryDominant = _chunkCAN76NCUcjs.secondaryDominant; exports.tensionCurve = _chunkRC6GBMCDcjs.tensionCurve; exports.tensionCurveFrom = _chunkRC6GBMCDcjs.tensionCurveFrom; exports.toVoiceNotes = _chunkRC6GBMCDcjs.toVoiceNotes;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.MODAL_SCALE_NAMES = _chunkOE6WK2Y2cjs.MODAL_SCALE_NAMES; exports.NoteSafety = _chunkUADYAYATcjs.NoteSafety; exports.analyzeArrangement = _chunk3JXCW6DXcjs.analyzeArrangement; exports.analyzeChord = _chunkOE6WK2Y2cjs.analyzeChord; exports.analyzeVoice = _chunk3JXCW6DXcjs.analyzeVoice; exports.augmentedSixthChord = _chunkOE6WK2Y2cjs.augmentedSixthChord; exports.augmentedSixthFromPitchClasses = _chunkOE6WK2Y2cjs.augmentedSixthFromPitchClasses; exports.augmentedSixthKind = _chunkOE6WK2Y2cjs.augmentedSixthKind; exports.borrowedSource = _chunkOE6WK2Y2cjs.borrowedSource; exports.chordTimelineFromChords = _chunk3JXCW6DXcjs.chordTimelineFromChords; exports.chordTimelineFromNotes = _chunk3JXCW6DXcjs.chordTimelineFromNotes; exports.chordToRoman = _chunkOE6WK2Y2cjs.chordToRoman; exports.compareMelodies = _chunk3JXCW6DXcjs.compareMelodies; exports.createArrangementSession = _chunk3JXCW6DXcjs.createArrangementSession; exports.detectCadence = _chunkOE6WK2Y2cjs.detectCadence; exports.detectCadences = _chunk3JXCW6DXcjs.detectCadences; exports.detectChord = _chunkOE6WK2Y2cjs.detectChord; exports.detectChordBest = _chunkOE6WK2Y2cjs.detectChordBest; exports.detectKey = _chunkOE6WK2Y2cjs.detectKey; exports.detectKeyBest = _chunkOE6WK2Y2cjs.detectKeyBest; exports.detectKeyFromNotes = _chunkOE6WK2Y2cjs.detectKeyFromNotes; exports.detectModulations = _chunk3JXCW6DXcjs.detectModulations; exports.explainRoman = _chunkOE6WK2Y2cjs.explainRoman; exports.extractMotifs = _chunk3JXCW6DXcjs.extractMotifs; exports.functionOf = _chunkOE6WK2Y2cjs.functionOf; exports.hypermeter = _chunk3JXCW6DXcjs.hypermeter; exports.isBorrowedChord = _chunkOE6WK2Y2cjs.isBorrowedChord; exports.isDiatonic = _chunkOE6WK2Y2cjs.isDiatonic; exports.isMinorKey = _chunkOE6WK2Y2cjs.isMinorKey; exports.keyTimelineFromNotes = _chunk3JXCW6DXcjs.keyTimelineFromNotes; exports.melodicContour = _chunk3JXCW6DXcjs.melodicContour; exports.melodicSimilarity = _chunk3JXCW6DXcjs.melodicSimilarity; exports.motifFromNotes = _chunk3JXCW6DXcjs.motifFromNotes; exports.phrasesFromTimeline = _chunk3JXCW6DXcjs.phrasesFromTimeline; exports.pivotChords = _chunkOE6WK2Y2cjs.pivotChords; exports.prevailingKeyOf = _chunk3JXCW6DXcjs.prevailingKeyOf; exports.reduceProgression = _chunk3JXCW6DXcjs.reduceProgression; exports.relateMotifs = _chunk3JXCW6DXcjs.relateMotifs; exports.romanToChord = _chunkOE6WK2Y2cjs.romanToChord; exports.secondaryDominant = _chunkOE6WK2Y2cjs.secondaryDominant; exports.secondaryDominantOf = _chunkOE6WK2Y2cjs.secondaryDominantOf; exports.sectionsFromNotes = _chunk3JXCW6DXcjs.sectionsFromNotes; exports.spellAugmentedSixth = _chunkOE6WK2Y2cjs.spellAugmentedSixth; exports.spellLine = _chunkMXO72PLYcjs.spellLine; exports.structuralCadences = _chunk3JXCW6DXcjs.structuralCadences; exports.tensionCurve = _chunk3JXCW6DXcjs.tensionCurve; exports.tensionCurveFrom = _chunk3JXCW6DXcjs.tensionCurveFrom; exports.toVoiceNotes = _chunk3JXCW6DXcjs.toVoiceNotes;
 //# sourceMappingURL=index.cjs.map

package/dist/analyze/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/libcantus/libcantus/dist/analyze/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,g7CAAC","file":"/home/runner/work/libcantus/libcantus/dist/analyze/index.cjs"}
+{"version":3,"sources":["/home/runner/work/libcantus/libcantus/dist/analyze/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,23FAAC","file":"/home/runner/work/libcantus/libcantus/dist/analyze/index.cjs"}