@libraz/libcantus 1.0.1 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @libraz/libcantus
 
-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.
+Pure-TypeScript music theory for MIDI note events. Recover the harmony from notes, and write new parts against that same reading. 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)
@@ -10,9 +10,11 @@ Pure-TypeScript music theory for MIDI note events. Build and spell chords, inspe
 [![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 it does
+![From note events to parts, and back](docs/images/pipeline.svg)
+
+The library 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. Note events go in, the harmony comes out, and the generators write against the harmony that was just read.
 
-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:
+## What it does
 
 ```ts
 import { Composer, Score } from '@libraz/libcantus';
@@ -31,84 +33,44 @@ Composer.of({ key: chords.key, bpm: 120, seed: 1 }).bass(chords, { style: 'walki
 // 16 notes: [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 100 }, ...]
 ```
 
-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.
-
-What each layer covers:
-
-- **[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.
-
-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.
-
-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.
+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. Answers carry their evidence: a chord analysis, a cadence and a Roman numeral each come with a `rationale` and the readings they turned down, and where the input cannot settle a question the field comes back `null` rather than a plausible guess.
 
-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).
+## Use cases
 
-## What it doesn't do
-
-- **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`.
-
-## Requirements
-
-Node.js >= 22.
+| Use case | What it does | Worked guide |
+|---|---|---|
+| A DAW assistant | Infers the harmony from tracks, then writes a bass line against it. | [DAW workflow](https://github.com/libraz/libcantus/blob/main/docs/en/use-cases/daw-workflow.md) |
+| A piece analyzer | Key regions, cadences, harmonic reduction, phrases, sections and motifs from one score. | [Piece analysis](https://github.com/libraz/libcantus/blob/main/docs/en/use-cases/piece-analysis.md) |
+| A modulation report | Key changes with their pivot chords, confidences and relations. | [Modulation report](https://github.com/libraz/libcantus/blob/main/docs/en/use-cases/modulation-report.md) |
+| A harmony exercise checker | Part-writing and species-counterpoint violations, each with the voice it happened in and the rule it broke. | [Harmony exercise checker](https://github.com/libraz/libcantus/blob/main/docs/en/use-cases/harmony-exercise-checker.md) |
+| A generative arrangement | One seeded composer writing a progression, its parts and its drums, then a playability check. | [Generative arrangement](https://github.com/libraz/libcantus/blob/main/docs/en/use-cases/generative-arrangement.md) |
+| A chord chart importer | Typed chord symbols turned into a timeline, voicings and a bass line. | [Chord chart import](https://github.com/libraz/libcantus/blob/main/docs/en/use-cases/chord-chart-import.md) |
+| Part preparation | A part fitted to an instrument and written at the pitch its player reads. | [Part preparation](https://github.com/libraz/libcantus/blob/main/docs/en/use-cases/part-preparation.md) |
 
 ## Install
 
+Node.js 22 or later.
+
 ```sh
 yarn add @libraz/libcantus
 ```
 
-## Quick start
-
-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 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]
-```
-
-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.
-
-## Import paths
-
-The package root exports everything. To pull in a single layer, import its subpath instead:
-
-```ts
-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
-```
-
-Both ESM and CommonJS builds ship for every path.
+The package root exports the whole API. `@libraz/libcantus/core`, `/theory`, `/analyze`, `/generate` and `/model` are narrower import boundaries onto the same symbols, and every path ships an ESM and a CommonJS build.
 
 ## Documentation
 
-Start here: [Introduction](docs/en/introduction.md), [Getting started](docs/en/getting-started.md), [Use cases](docs/en/use-cases/index.md).
+New to music theory? [The primer](https://github.com/libraz/libcantus/blob/main/docs/en/primer/index.md) teaches the concepts this API is built on — pitch and intervals, scales and keys, chords, harmony, voices, rhythm and meter — for a reader who writes TypeScript rather than scores.
 
-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).
+Otherwise start at [Introduction](https://github.com/libraz/libcantus/blob/main/docs/en/introduction.md) and [Getting started](https://github.com/libraz/libcantus/blob/main/docs/en/getting-started.md), which index the domain guides and the reference pages. Every `ts` example in the guides is executed by the test suite, and a trailing comment that names a literal — with or without the reason for it after an em dash — is checked against what the call returns.
 
-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).
+## What it doesn't do
 
-Reference: [API reference](docs/en/api-reference.md), [Glossary](docs/en/glossary.md), [Questions and limitations](docs/en/faq.md).
+- **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. For the layer below, [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.
+- **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 grammar built on it.
+- **No corpus.** Nothing is bundled to run statistics over.
 
-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.
+[Questions and limitations](https://github.com/libraz/libcantus/blob/main/docs/en/faq.md) covers the rest, including where a functional reading does not apply and what the engine will not guess.
 
 ## License
 

package/README_ja.md

@@ -1,6 +1,6 @@
 # @libraz/libcantus
 
-MIDI ノートイベントを扱う、TypeScript 製の音楽理論ライブラリです。コードの組み立てと綴り、和声とキーの解析、曲の形式の読み取り、パート生成を同じデータモデルで行えます。実行時依存はありません。
+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)
@@ -10,9 +10,11 @@ MIDI ノートイベントを扱う、TypeScript 製の音楽理論ライブラ
 [![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/)
 
-## できること
+![ノートイベントからパートへ、そして再びノートイベントへ](docs/images/pipeline-ja.svg)
+
+このライブラリは、すでにノートやコード記号を持っているソフトウェア（DAW のプロジェクト、MIDI パーサー、練習支援ツールなど）と、その音が和声的に何を意味するかとの間を埋めます。ノートイベントを渡すと和声が求まり、ジェネレーターはいま読み取ったその和声に沿ってパートを書きます。
 
-すでにノートやコード記号を持っているソフトウェア（DAW のプロジェクト、MIDI パーサー、練習支援ツールなど）と、その音が和声的に何を意味するかとの間を埋めます。ノートイベントを渡せば和声が求まり、その和声を渡せばそれに沿ったパートが書けます。
+## できること
 
 ```ts
 import { Composer, Score } from '@libraz/libcantus';
@@ -31,85 +33,45 @@ Composer.of({ key: chords.key, bpm: 120, seed: 1 }).bass(chords, { style: 'walki
 // 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` を返します。カデンツが完全か不完全かはヴォイシングがなければ決まりません。ソプラノに何があるかはヴォイシングだけが答えられるからです。
+コードの境界は決め打ちせずに探索し、キーも同様に探します。転調する曲を、冒頭のキーのまま読み続けることはありません。答えには根拠が伴います。コード分析・終止・ローマ数字はいずれも `rationale` と、退けた候補を併せて返し、入力だけでは決まらない項目は、もっともらしい推測ではなく `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。
+| ユースケース | 内容 | 実例のガイド |
+|---|---|---|
+| DAW のアシスタント | トラックから和声を読み取り、それに沿ってベースラインを書く。 | [DAW ワークフロー](docs/ja/use-cases/daw-workflow.md) |
+| 楽曲アナライザー | 1 つのスコアから調区間、終止形、和声的な還元、フレーズ、セクション、モチーフを得る。 | [楽曲の解析](docs/ja/use-cases/piece-analysis.md) |
+| 転調レポート | 転調を、軸和音・確信度・調同士の関係とともに提示する。 | [転調レポート](docs/ja/use-cases/modulation-report.md) |
+| 和声課題のチェッカー | 声部書法と種目対位法の違反を、違反した声部と破った規則つきで報告する。 | [和声課題のチェック](docs/ja/use-cases/harmony-exercise-checker.md) |
+| 自動生成アレンジ | シードを固定した 1 つのコンポーザーがコード進行・各パート・ドラムを書き、演奏可能性を確認する。 | [生成によるアレンジ](docs/ja/use-cases/generative-arrangement.md) |
+| コード譜の取り込み | 打ち込んだコード記号をタイムライン、ヴォイシング、ベースラインに変換する。 | [コード譜の取り込み](docs/ja/use-cases/chord-chart-import.md) |
+| パート譜の準備 | パートを楽器に合わせ、その奏者が読む音高で書き出す。 | [パート譜の準備](docs/ja/use-cases/part-preparation.md) |
 
 ## インストール
 
+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 の両方のビルドがあります。
+パッケージのルートから API 全体を公開しています。`@libraz/libcantus/core`、`/theory`、`/analyze`、`/generate`、`/model` は同じシンボル群に対する、より狭い読み込み境界です。いずれのパスも ESM と CommonJS の両方のビルドを同梱しています。
 
 ## ドキュメント
 
-最初に読むページ: [概要](docs/ja/introduction.md)、[使い始める](docs/ja/getting-started.md)、[ユースケース](docs/ja/use-cases/index.md)。
+音楽理論にはじめて触れる場合は、[入門ガイド](docs/ja/primer/index.md)から始めてください。この API が土台にしている考え方 — 音高と音程、音階と調、和音、和声、声部、リズムと拍子 — を、楽譜ではなく TypeScript を書く読者に向けて説明しています。
 
-各領域のガイド: [音高と記譜](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/introduction.md)と[使いはじめる](docs/ja/getting-started.md)から読んでください。各分野のガイドとリファレンスはそこから辿れます。ガイド中の `ts` の例はすべてテストスイートで実行され、行末コメントがリテラルを名指していれば（em ダッシュに続けて理由が書かれていてもかまいません）実際の戻り値と照合されます。
 
-横断的な話題: [決定性とシード](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)。
+- **入出力・記譜・音声は扱いません。** MIDI ファイルの読み書き、楽譜の描画、音声解析、再生はいずれも対象外です。パーサーは呼び出し側で用意し、ノートイベントを渡してください。その下の層が必要な場合、[libsonare](https://github.com/libraz/libsonare) が音声解析・マスタリング・合成・SMF の入出力を扱います。両者はコードを共有せず、どちらも他方を必要としません。
+- **微分音の解析は行いません。** 周波数、セント、オクターブの等分割、純正律の比は `core` にありますが、音高より上の層はすべて 12 のピッチクラスで動きます。
+- **旋法体系そのものは扱いません。** `WORLD_SCALES` が記録するのは、その伝統が名前を与えている音の素材 — ターット、マカームの音組織、日本の五音音階 — であって、その上に築かれた語法ではありません。
+- **コーパスは同梱しません。** 統計を取るためのデータは含みません。
 
-これらのガイドの `ts` の例はすべてテストスイートで実行され、末尾コメントに書いた期待値は実際の返り値と照合されます。生成される TypeDoc のリファレンスは `docs/api` に出力され、手書きガイドとは分かれています。
+残りは[疑問と制限](docs/ja/faq.md)にまとめています。機能和声の読みが適用できない場合や、エンジンが推測しないことについてもそこで扱います。
 
 ## ライセンス
 
-[@libraz/libcantus](https://github.com/libraz/libcantus) は [Apache License 2.0](LICENSE) で提供します。
+[@libraz/libcantus](https://github.com/libraz/libcantus) は [Apache License 2.0](LICENSE) で公開しています。

package/dist/analyze/index.cjs

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkMXO72PLYcjs = require('../chunk-MXO72PLY.cjs');
+var _chunkHWHGOVO6cjs = require('../chunk-HWHGOVO6.cjs');
 
 
 
@@ -18,6 +18,7 @@ var _chunkMXO72PLYcjs = require('../chunk-MXO72PLY.cjs');
 
 
 
+var _chunkHPVSH7SFcjs = require('../chunk-HPVSH7SF.cjs');
 
 
 
@@ -25,7 +26,6 @@ var _chunkMXO72PLYcjs = require('../chunk-MXO72PLY.cjs');
 
 
 
-var _chunkB6XNKWZVcjs = require('../chunk-B6XNKWZV.cjs');
 
 
 
@@ -50,14 +50,14 @@ var _chunkB6XNKWZVcjs = require('../chunk-B6XNKWZV.cjs');
 
 
 
-var _chunkOE6WK2Y2cjs = require('../chunk-OE6WK2Y2.cjs');
-require('../chunk-K4ZJUGF4.cjs');
 
 
-var _chunkUADYAYATcjs = require('../chunk-UADYAYAT.cjs');
-require('../chunk-Q2WGKJNN.cjs');
+var _chunkSGLEQVJHcjs = require('../chunk-SGLEQVJH.cjs');
+require('../chunk-35NBV2FT.cjs');
 
 
+var _chunk3R3QVKY5cjs = require('../chunk-3R3QVKY5.cjs');
+require('../chunk-S5BKZZGM.cjs');
 
 
 
@@ -105,5 +105,9 @@ require('../chunk-Q2WGKJNN.cjs');
 
 
 
-exports.MODAL_SCALE_NAMES = _chunkOE6WK2Y2cjs.MODAL_SCALE_NAMES; exports.NoteSafety = _chunkUADYAYATcjs.NoteSafety; exports.analyzeArrangement = _chunkB6XNKWZVcjs.analyzeArrangement; exports.analyzeChord = _chunkOE6WK2Y2cjs.analyzeChord; exports.analyzeVoice = _chunkB6XNKWZVcjs.analyzeVoice; exports.augmentedSixthChord = _chunkOE6WK2Y2cjs.augmentedSixthChord; exports.augmentedSixthFromPitchClasses = _chunkOE6WK2Y2cjs.augmentedSixthFromPitchClasses; exports.augmentedSixthKind = _chunkOE6WK2Y2cjs.augmentedSixthKind; exports.borrowedSource = _chunkOE6WK2Y2cjs.borrowedSource; exports.chordTimelineFromChords = _chunkB6XNKWZVcjs.chordTimelineFromChords; exports.chordTimelineFromNotes = _chunkB6XNKWZVcjs.chordTimelineFromNotes; exports.chordToRoman = _chunkOE6WK2Y2cjs.chordToRoman; exports.compareMelodies = _chunkB6XNKWZVcjs.compareMelodies; exports.createArrangementSession = _chunkB6XNKWZVcjs.createArrangementSession; exports.detectCadence = _chunkOE6WK2Y2cjs.detectCadence; exports.detectCadences = _chunkB6XNKWZVcjs.detectCadences; exports.detectChord = _chunkOE6WK2Y2cjs.detectChord; exports.detectChordBest = _chunkOE6WK2Y2cjs.detectChordBest; exports.detectKey = _chunkOE6WK2Y2cjs.detectKey; exports.detectKeyBest = _chunkOE6WK2Y2cjs.detectKeyBest; exports.detectKeyFromNotes = _chunkOE6WK2Y2cjs.detectKeyFromNotes; exports.detectModulations = _chunkB6XNKWZVcjs.detectModulations; exports.explainRoman = _chunkOE6WK2Y2cjs.explainRoman; exports.extractMotifs = _chunkB6XNKWZVcjs.extractMotifs; exports.functionOf = _chunkOE6WK2Y2cjs.functionOf; exports.hypermeter = _chunkB6XNKWZVcjs.hypermeter; exports.isBorrowedChord = _chunkOE6WK2Y2cjs.isBorrowedChord; exports.isDiatonic = _chunkOE6WK2Y2cjs.isDiatonic; exports.isMinorKey = _chunkOE6WK2Y2cjs.isMinorKey; exports.keyTimelineFromNotes = _chunkB6XNKWZVcjs.keyTimelineFromNotes; exports.melodicContour = _chunkB6XNKWZVcjs.melodicContour; exports.melodicSimilarity = _chunkB6XNKWZVcjs.melodicSimilarity; exports.motifFromNotes = _chunkB6XNKWZVcjs.motifFromNotes; exports.phrasesFromTimeline = _chunkB6XNKWZVcjs.phrasesFromTimeline; exports.pivotChords = _chunkOE6WK2Y2cjs.pivotChords; exports.prevailingKeyOf = _chunkB6XNKWZVcjs.prevailingKeyOf; exports.reduceProgression = _chunkB6XNKWZVcjs.reduceProgression; exports.relateMotifs = _chunkB6XNKWZVcjs.relateMotifs; exports.romanToChord = _chunkOE6WK2Y2cjs.romanToChord; exports.secondaryDominant = _chunkOE6WK2Y2cjs.secondaryDominant; exports.secondaryDominantOf = _chunkOE6WK2Y2cjs.secondaryDominantOf; exports.sectionsFromNotes = _chunkB6XNKWZVcjs.sectionsFromNotes; exports.spellAugmentedSixth = _chunkOE6WK2Y2cjs.spellAugmentedSixth; exports.spellLine = _chunkMXO72PLYcjs.spellLine; exports.structuralCadences = _chunkB6XNKWZVcjs.structuralCadences; exports.tensionCurve = _chunkB6XNKWZVcjs.tensionCurve; exports.tensionCurveFrom = _chunkB6XNKWZVcjs.tensionCurveFrom; exports.toVoiceNotes = _chunkB6XNKWZVcjs.toVoiceNotes;
+
+
+
+
+exports.MODAL_SCALE_NAMES = _chunkSGLEQVJHcjs.MODAL_SCALE_NAMES; exports.NoteSafety = _chunk3R3QVKY5cjs.NoteSafety; exports.analyzeArrangement = _chunkHPVSH7SFcjs.analyzeArrangement; exports.analyzeChord = _chunkSGLEQVJHcjs.analyzeChord; exports.analyzePolyphony = _chunkHPVSH7SFcjs.analyzePolyphony; exports.analyzeVoice = _chunkSGLEQVJHcjs.analyzeVoice; exports.assertChordTimeline = _chunkSGLEQVJHcjs.assertChordTimeline; exports.augmentedSixthChord = _chunkSGLEQVJHcjs.augmentedSixthChord; exports.augmentedSixthFromPitchClasses = _chunkSGLEQVJHcjs.augmentedSixthFromPitchClasses; exports.augmentedSixthKind = _chunkSGLEQVJHcjs.augmentedSixthKind; exports.borrowedSource = _chunkSGLEQVJHcjs.borrowedSource; exports.chordTimelineFromChords = _chunkSGLEQVJHcjs.chordTimelineFromChords; exports.chordTimelineFromNotes = _chunkSGLEQVJHcjs.chordTimelineFromNotes; exports.chordToRoman = _chunkSGLEQVJHcjs.chordToRoman; exports.compareMelodies = _chunkHPVSH7SFcjs.compareMelodies; exports.createArrangementSession = _chunkHPVSH7SFcjs.createArrangementSession; exports.detectCadence = _chunkSGLEQVJHcjs.detectCadence; exports.detectCadences = _chunkSGLEQVJHcjs.detectCadences; exports.detectChord = _chunkSGLEQVJHcjs.detectChord; exports.detectChordBest = _chunkSGLEQVJHcjs.detectChordBest; exports.detectKey = _chunkSGLEQVJHcjs.detectKey; exports.detectKeyBest = _chunkSGLEQVJHcjs.detectKeyBest; exports.detectKeyFromNotes = _chunkSGLEQVJHcjs.detectKeyFromNotes; exports.detectModulations = _chunkSGLEQVJHcjs.detectModulations; exports.explainRoman = _chunkSGLEQVJHcjs.explainRoman; exports.extractMotifs = _chunkHPVSH7SFcjs.extractMotifs; exports.functionOf = _chunkSGLEQVJHcjs.functionOf; exports.hypermeter = _chunkHPVSH7SFcjs.hypermeter; exports.isBorrowedChord = _chunkSGLEQVJHcjs.isBorrowedChord; exports.isDiatonic = _chunkSGLEQVJHcjs.isDiatonic; exports.isMinorKey = _chunkSGLEQVJHcjs.isMinorKey; exports.keyTimelineFromNotes = _chunkSGLEQVJHcjs.keyTimelineFromNotes; exports.melodicContour = _chunkHPVSH7SFcjs.melodicContour; exports.melodicSimilarity = _chunkHPVSH7SFcjs.melodicSimilarity; exports.motifFromNotes = _chunkHPVSH7SFcjs.motifFromNotes; exports.phrasesFromTimeline = _chunkHPVSH7SFcjs.phrasesFromTimeline; exports.pivotChords = _chunkSGLEQVJHcjs.pivotChords; exports.prevailingKeyOf = _chunkSGLEQVJHcjs.prevailingKeyOf; exports.reduceProgression = _chunkHPVSH7SFcjs.reduceProgression; exports.relateMotifs = _chunkHPVSH7SFcjs.relateMotifs; exports.romanToChord = _chunkSGLEQVJHcjs.romanToChord; exports.secondaryDominant = _chunkSGLEQVJHcjs.secondaryDominant; exports.secondaryDominantOf = _chunkSGLEQVJHcjs.secondaryDominantOf; exports.sectionsFromNotes = _chunkHPVSH7SFcjs.sectionsFromNotes; exports.spellAugmentedSixth = _chunkSGLEQVJHcjs.spellAugmentedSixth; exports.spellLine = _chunkHWHGOVO6cjs.spellLine; exports.structuralCadences = _chunkHPVSH7SFcjs.structuralCadences; exports.tensionCurve = _chunkHPVSH7SFcjs.tensionCurve; exports.tensionCurveFrom = _chunkHPVSH7SFcjs.tensionCurveFrom; exports.toVoiceNotes = _chunkSGLEQVJHcjs.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;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"}
+{"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;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;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;AACA;AACA;AACF,+/FAAC","file":"/home/runner/work/libcantus/libcantus/dist/analyze/index.cjs"}