@libraz/libcantus 0.9.5 → 1.0.0

package/README_ja.md

@@ -1,268 +1,115 @@
 # @libraz/libcantus
 
-TypeScript だけで書かれた音楽理論エンジンです。MIDI ノート番号とコードネームを受け取り、和声的な意味（ローマ数字、和声機能、終止、キー）を返します。さらにその解析結果を土台にして新しいパートを生成します。DAW の隣に置くツール（解析器、ジェネレーター、作曲アシスタント）で使うことを想定しています。
-
-扱うのは理論の層だけで、I/O やオーディオには踏み込みません。MIDI ファイルの読み書き、オーディオ解析、再生のいずれも持たないので、パースは呼び出し側で行い、ノートイベントとして渡してください。実行時依存はありません。その層も必要であれば、[libsonare](https://github.com/libraz/libsonare) が音声解析・マスタリング・音源合成・SMF の読み書きを担当していて、npm パッケージなので本ライブラリと並べて置けます。両者はコードを共有しておらず、どちらも単独で使えます。
+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-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/)
 
-## 何ができるか
-
-- **音名を扱う** — `C4` のパース、移調、MIDI との相互変換、異名同音を区別した音程の綴り（`F#` と `Gb`）。
-- **コードと進行を組み立てる** — スケール度数、ローマ数字（`V7/V`）、リードシート記号（`Cmaj7`, `F#m7b5`, `C/G`）のいずれからでも。
-- **和声を解析する** — ローマ数字解析、和声機能、終止形の検出、借用和音とモーダルインターチェンジ。
-- **コードとキーを判定する** — ノートを入れるとコードやキーが返る、組み立ての逆方向の処理。
-- **リハーモナイズする** — 裏コード、クロマチックメディアント、ネガティブハーモニー、モーダルインターチェンジのパレット。
-- **コードをボイシングする** — 声部の動きを最小化した 4 声（SATB）に加えて、drop-2/3、シェル、ルートレスのコンピングスタイル。
-- **パートを生成する** — ベースライン、対旋律、ドラム、リズム、モチーフ、進行全体。シードを与えれば結果は決定的になります。
-- **アレンジ全体を解析する** — マルチトラックのノートイベントを渡すと和声を復元し、曲全体の解析（ノート単位の衝突検出つき）を返します。そこから足りないパートを生成できます。
-- **音高を音響として扱う** — 周波数、セント、EDO、純正律。
-
-理論の本体は tree-shaking の効く純粋関数として実装してあります。その上に、音楽理論の記述に近い形で書ける不変（immutable）なクラス API（`Note`, `Interval`, `Chord`, `Key`, `Progression`）が乗ります。どちらの形で提供されるかは一つの規則で決まります。音符・コード・キー・進行といった値は両方の形を持ち、相互に行き来できます。一方でコレクションやタイムラインを対象とする操作（パート生成、アレンジ全体の解析、キーのランキング）はノートイベントの配列を受け取るため、関数としてのみ公開されます。
-
-## インストール
-
-```sh
-yarn add @libraz/libcantus
-```
-
-## サブパスインポート
-
-パッケージのルートからはすべてがエクスポートされます。特定の層だけを取り込みたい場合は、その層のサブパスからインポートしてください。
-
-```ts
-import { Chord, Key, Note } from '@libraz/libcantus/model'; // クラス API
-import { majorKey, makeChord } from '@libraz/libcantus/theory'; // スケール、コード
-import { generateDrums, generateProgression } from '@libraz/libcantus/generate';
-import { analyzeArrangement, detectKey } from '@libraz/libcantus/analyze';
-import { parseNote, edo } from '@libraz/libcantus/core'; // 音高、拍子、音律
-```
-
-層は `core`, `theory`, `analyze`, `generate`, `model` の 5 つです。
-
-## クイックスタート
-
-クラス API は不変のままメソッドチェーンでき、キーの文脈を持ち回るので、解析のたびにキーを渡し直す必要はありません。
-
-```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 ノート ]  (セカンダリードミナントをボイシング)
-Note.of('C4').transpose(7).name; // 'G4'
-
-// ii–V–I を組み立てて、そのまま 1 行で解析する:
-c.chord(1, 'min').progressionTo(c.chord(4, 'dom7'), c.chord(0, 'maj')).analyze();
-// { chords: [...機能和声の解析...], cadence: 'authentic' }
-
-Chord.detect([60, 64, 67])[0].quality; // 'maj'
-```
-
-どのクラスもプレーンなオブジェクト（`Chord.data`, `Note.data`）を包んでいるだけで、処理は純粋関数に委譲されます。そのため二つのスタイルは自由に混ぜられます。同じ処理を関数 API で書くとこうなります。
-
-```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)
-```
-
-## 音名を扱う
-
-音名のパースと整形、MIDI への変換、そしてピッチクラスの層では区別できない異名同音を正しく綴り分ける音程計算ができます。
-
-```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'  (増四度)
-Interval.between(Note.of('C4'), Note.of('Gb4')).name; // 'd5'  (減五度)
-```
-
-## キーとスケール
-
-`KeyScale` はルートのピッチクラスと 12 ビットの `modeMask12` の組です（ビット `n` が立っていれば、ピッチクラス `(rootPc + n) % 12` がスケールに含まれます）。`majorKey`, `minorKey`, `scaleByName` が教会旋法・ペンタトニック・ブルース・ホールトーン・オクタトニックをカバーし、`MAJOR_MASK` と `NATURAL_MINOR_MASK` を使えば独自のキーも定義できます。
-
-`nearestScaleTone` は与えた音高を最も近いスケール構成音の MIDI ノートにスナップします（同距離なら低い方を優先）。生成した音をキーに収める場面で使えます。
-
-## コードと進行を組み立てる
-
-スケール度数、ローマ数字、リードシート記号のいずれからでも組み立てられ、逆方向にも戻せます。
+## できること
 
-```ts
-import { Chord, Key } from '@libraz/libcantus';
-
-const c = Key.major('C');
-
-c.roman('V7/V').symbol(); // 'D7'  (セカンダリードミナント)
-c.chord(4, 'dom7').roman(); // 'V7'
-Chord.parse('F#m7b5').pitchClasses(); // [0, 4, 6, 9]
-```
-
-コードの語彙は三和音から 13th までを網羅していて、`dim7`, `m7b5`, `minMaj7`, `aug7`、6th 系、オルタードドミナントも含みます。
-
-スタイルのプリセットから進行そのものを生成することもできます（コレクション単位の操作なので関数として提供されます）。
-
-```ts
-import { generateProgression, majorKey } from '@libraz/libcantus';
-
-// 1 小節につき 1 コード。収まる箇所にはセカンダリードミナントを挿入する:
-generateProgression({ key: majorKey(0), style: 'idol', bars: 8, reharmonize: true, seed: 1 });
-```
-
-## 和声を解析する
-
-コードを、和声機能・終止・モーダルインターチェンジつきのローマ数字解析に変換します。長調と短調の双方に対応し、転回形も反映されます。
+すでにノートやコード記号を持っているソフトウェア（DAW のプロジェクト、MIDI パーサー、練習支援ツールなど）と、その音が和声的に何を意味するかとの間を埋めます。ノートイベントを渡せば和声が求まり、その和声を渡せばそれに沿ったパートが書けます。
 
 ```ts
-import { Chord, Key } from '@libraz/libcantus';
+import { Composer, Score } from '@libraz/libcantus';
 
-// 長調に現れる短調の iv は、借用されたサブドミナントとして解釈される:
-Chord.of('F', 'min').analyze(Key.major('C'));
-// { function: 'subdominant', borrowed: true, source: 'parallelMinor', roman: 'iv' }
-```
-
-## コードとキーを判定する
+// 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'
 
-```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 メジャー  (キーのランキングは関数として提供)
+// 求まった和声の上に、ウォーキングベースを書く:
+Composer.of({ key: chords.key, bpm: 120, seed: 1 }).bass(chords, { style: 'walking' }).notes;
+// 16 音: [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 100 }, ...]
 ```
 
-## コードとスケールを綴る
-
-`Key` は綴りを持ったトニックを保持しているので、ピッチクラスで動くコア部分からでも音名の文字列が得られます。長調でも短調でも綴りは正しくなります。
-
-```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']
+各レイヤーが受け持つ範囲は次のとおりです。
 
-// コードもキーの文脈に沿って綴られる:
-Key.major('C').chord(4, 'dom7').spell().map((n) => n.name); // ['G', 'B', 'D', 'F']
-```
+- **[音高と記譜](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 度はピッチクラス上の距離が同じでも同じ音程ではないので、声部書法と対位法のチェッカーは数値ではなく綴られた音を受け取ります。
 
-```ts
-import { Chord, Key, majorKey, parseChordSymbol, substituteChord } from '@libraz/libcantus';
+アプリケーションが手元に持っているデータから始まるガイドが 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)です。
 
-Key.major('C').chord(4, 'dom7').negativeHarmony().symbol(); // 'Dm7b5'
+## やらないこと
 
-// 代理コードやパレットの検索はリストを返すので関数として提供される:
-substituteChord(parseChordSymbol('G7'), majorKey(0));
-// [{ chord: Db7, type: 'tritone', ... }, ...]
-```
+- **入出力・記譜・音声を扱いません。** MIDI ファイルの読み書き、楽譜の描画、音声解析、再生はありません。パーサーは各自で用意し、ノートイベントとして渡してください。その層こそが必要なら、[libsonare](https://github.com/libraz/libsonare) が音声解析、マスタリング、合成、SMF 入出力を扱います。両者はコードを共有せず、どちらも相手を必要としません。
+- **微分音の解析はしません。** 周波数、セント、オクターブの等分割、純正律の比は `core` にありますが、音高より上の層はすべて 12 のピッチクラスで動きます。半音より細かい単位で組み立てられた音楽は範囲外です。半フラットの音度を持つマカームを 12 音の近い音で代用せず `WORLD_SCALES` から外しているのも、同じ理由です。
+- **旋法体系そのものは扱いません。** `WORLD_SCALES` が収録するのは、thāt やマカーム、日本の音階といった伝統が名を与えた音組織であって、その上に立つ体系ではありません。上行形と下行形、フレーズが寄りかかる音、旋律型の文法は、マスクには入りません。
+- **調性を前提にしません。** ローマ数字と機能和声は西洋の慣習を前提とします。その読み方が適用できるスケールかどうかは `supportsFunctionalHarmony` が答えます（`'dorian'` は真、`'miyakoBushi'` は偽）。
+- **コーパスは持ちません。** 統計を取るためのデータは同梱していません。
+- **機能和声には既知の穴があります。** `functionOf` は和音と調だけから答えるため、終止四六の和音はその層では主和音の転回として読まれます。属和音としての読みは時間軸を見る層のものであり、属和音の前の和音を `approach` として渡したときに `detectCadence` がそれを示します。
 
-## スケールとテンションを選ぶ
+## 要件
 
-クラス側で、あるコードに使えるスケールと、そこで利用できるテンションおよびアボイドノートを求められます。`scalesForChanges` を使えば、コード進行全体を通して繋がりが最適になるスケール選択が得られます。
+Node.js >= 22。
 
-```ts
-import { Chord } from '@libraz/libcantus';
+## インストール
 
-Chord.of('C', 'dom7').scales()[0]; // { name: 'mixolydian', rootPc: 0 }
-Chord.of('C', 'maj7').tensions('ionian'); // [2, 9]  (9th と 13th。11th はアボイドノート)
+```sh
+yarn add @libraz/libcantus
 ```
 
-## コードをボイシングする
+## 最初の例
 
-進行全体を、声部の動きが最小になる 4 声（SATB）の MIDI ボイシングに展開できます。単体のコードをコンピングスタイル（drop-2/3、シェル、ルートレス）でボイシングすることもできます。
+理論の本体はツリーシェイク可能な純粋関数にあります。その上に、理論を語るときの言い方に近い不変のクラス API が乗っています。ライブラリが扱う対象ごとに1つのクラスがあり、単体の `Note`、`Interval`、`Chord` から、曲全体を受け持つ `Score`、`Timeline`、`Arrangement`、`Composer` までが揃います。
 
 ```ts
 import { Chord, Key } from '@libraz/libcantus';
 
-const c = Key.major('C');
-
-// 進行全体を、動きが最小になるようボイシングする:
-c.chord(0, 'maj').progressionTo(c.chord(5, 'maj'), c.chord(4, 'dom7'), c.chord(0, 'maj')).voice();
-// [[...], [...], [...], [...]]  (各声部の音高が昇順に並ぶ)
-
-// 単体のコードをシェルボイシングで:
-Chord.of('C', 'maj7').styledVoicing({ style: 'shell' }); // ルート、3rd、7th
-```
-
-声部の進行を細かく制御したい場合は `voiceLeadingCost` と `nextVoicing` を、結果を検証したい場合は `counterpoint` の述語群（並行・隠伏の完全音程、音域の間隔、声部の交差、導音の解決など）を使います。
+const key = Key.major('C');
+const dominant = key.chord(5, 'dom7');
 
-## パートを生成する
-
-旋律と伴奏のジェネレーターは、いずれもシードを取り決定的に動きます。
-
-```ts
-import {
-  generateBassLine, generateCounterMelody, generateDrums, generateRhythm,
-  generateMotif, majorKey, parseTimeSignature,
-} from '@libraz/libcantus';
-
-generateRhythm(parseTimeSignature('4/4'), { seed: 1, density: 0.5 }); // 強拍に重みを置いた発音位置
-const motif = generateMotif({ key: majorKey(0), bars: 2, contour: 'arch', seed: 1 });
-motif.notes.length > 0; // true — 決定的に生成された短い旋律の断片
+dominant.symbol(); // 'G7'
+dominant.analyze(key).roman; // 'V7'
+Chord.parse('C7(b9,#11)').pitchClasses(); // [0, 1, 4, 6, 7, 10]
 ```
 
-`humanize`, `extractGrooveTemplate`, `applyGrooveTemplate` は拍子を踏まえたノリを付け足します。ある演奏のノリを取り出して別の演奏に移植する使い方もできます。
+本体は関数で、クラスはいずれもその薄い外皮です。クラスは `.data` でプレーンな値を公開し、関数が返したデータからクラスを作れます。どちらかが閉じた世界になることはなく、返す答えも同じです。クラスが足すのは、値とその文脈をひとまとめに保持することです。呼び出しを連ねるときに同じ事実を書き直さずに済みます。`Score` は音符と拍子・テンポ・調をまとめて持ち、`Composer` は 1 曲を書くときの調・テンポ・シードを持ちます。
 
-## アレンジを解析して足す
+## インポートパス
 
-アレンジ層は、DAW や MIDI ファイルのパーサーが吐いたマルチトラックの `NoteEvent` をそのまま受け取り、和声を復元してから解析と生成を行います。
+ルートからすべてを export しています。1 つのレイヤーだけを取り込みたい場合は、サブパスを使ってください。
 
 ```ts
-import {
-  analyzeArrangement, chordTimelineFromNotes, generateBassLine, generateCounterMelody,
-} from '@libraz/libcantus';
-
-// 演奏されたノートからコード進行（とキー）を推定する:
-const { timeline, key } = chordTimelineFromNotes(melodyAndChordNotes);
-
-// 曲全体の解析。推定されたコード、終止、ノート単位の理論ラベル、そして
-// 鳴っている和声とぶつかるノート（理由と修正候補つき）が得られる:
-const report = analyzeArrangement([
-  { role: 'melody', notes: melodyNotes },
-  { role: 'harmony', notes: chordNotes },
-]);
-report.conflicts; // [{ beat, trackName, pitch, safety, reasons, rationale }, ...]
-
-// 復元されたタイムラインから、足りないパートを生成する:
-generateBassLine({ segments: timeline.segments, key, style: 'walking', seed: 1 });
-generateCounterMelody({ melody: melodyNotes, timeline, key, register: 'below' });
+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
 ```
 
-`harmonizeMelody` は逆方向を担当します。旋律だけを渡すと、それを和声づけするのに最適なキー・移調量・コードの経路を（必要ならリハーモナイズも含めて）探索します。
+いずれのパスにも ESM と CommonJS の両方のビルドがあります。
 
-アレンジ層と生成層のあいだでやり取りするノートイベントは `NoteEvent`（`{ pitch, startBeat, durationBeat, velocity? }`。音高は MIDI ノート番号、時間は 4 分音符を 1 とする拍数）の一種類に統一されています。シードを取るジェネレーター（`bass`, `groove`, `countermelody`, `rhythm`, `drums`, `motif`, `progression`）は、同じシードに対して常に同じ結果を返します。
+## ドキュメント
 
-## 音高を音響として扱う
+最初に読むページ: [概要](docs/ja/introduction.md)、[使い始める](docs/ja/getting-started.md)、[ユースケース](docs/ja/use-cases/index.md)。
 
-周波数、セント、EDO、純正律を扱えます。音律の設計、微分音、そして解析に使えます。
+各領域のガイド: [音高と記譜](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)。
 
-```ts
-import { frequencyOf, edo, justDeviationCents } from '@libraz/libcantus';
-```
+横断的な話題: [決定性とシード](docs/ja/determinism-and-seeding.md)、[エラーと検証](docs/ja/errors-and-validation.md)、[パフォーマンス](docs/ja/performance.md)、[相互運用](docs/ja/interoperability.md)。
 
-拍子まわりのヘルパー（`TimeSignature`, `parseTimeSignature`, `beatsPerBar`, `metricWeight`, `isStrongBeat`, `tuplet`）は単純拍子と複合拍子の両方を扱い、アクセントを考慮するジェネレーター群の土台にもなっています。
-
-## ドキュメント
+リファレンス: [API リファレンス](docs/ja/api-reference.md)、[用語集](docs/ja/glossary.md)、[FAQ と制限](docs/ja/faq.md)。
 
-すべてのエクスポートをシグネチャつきで、領域ごとに分類し、動かせる例を添えた API リファレンスをソースから生成して **[libraz.github.io/libcantus](https://libraz.github.io/libcantus/)** に公開しています。
+これらのガイドの `ts` の例はすべてテストスイートで実行され、末尾コメントに書いた期待値は実際の返り値と照合されます。生成される TypeDoc のリファレンスは `docs/api` に出力され、手書きガイドとは分かれています。
 
 ## ライセンス
 
-Apache-2.0
+[@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 _chunk4VZ5MZAMcjs = require('../chunk-4VZ5MZAM.cjs');
-require('../chunk-2A2QMA74.cjs');
 
 
 
@@ -26,12 +25,9 @@ require('../chunk-2A2QMA74.cjs');
 
 
 
-var _chunkKQN2ZYNDcjs = require('../chunk-KQN2ZYND.cjs');
+var _chunk3JXCW6DXcjs = require('../chunk-3JXCW6DX.cjs');
 
 
-var _chunkWFDXOLUBcjs = require('../chunk-WFDXOLUB.cjs');
-require('../chunk-BSLTLGM3.cjs');
-require('../chunk-PI3UXRWK.cjs');
 
 
 
@@ -54,9 +50,60 @@ require('../chunk-PI3UXRWK.cjs');
 
 
 
+var _chunkOE6WK2Y2cjs = require('../chunk-OE6WK2Y2.cjs');
+require('../chunk-K4ZJUGF4.cjs');
 
 
+var _chunkUADYAYATcjs = require('../chunk-UADYAYAT.cjs');
+require('../chunk-Q2WGKJNN.cjs');
 
 
-exports.NoteSafety = _chunkWFDXOLUBcjs.NoteSafety; exports.analyzeArrangement = _chunk4VZ5MZAMcjs.analyzeArrangement; exports.analyzeChord = _chunkKQN2ZYNDcjs.analyzeChord; exports.analyzeVoice = _chunk4VZ5MZAMcjs.analyzeVoice; exports.borrowedSource = _chunkKQN2ZYNDcjs.borrowedSource; exports.chordTimelineFromChords = _chunk4VZ5MZAMcjs.chordTimelineFromChords; exports.chordTimelineFromNotes = _chunk4VZ5MZAMcjs.chordTimelineFromNotes; exports.chordToRoman = _chunkKQN2ZYNDcjs.chordToRoman; exports.detectCadence = _chunkKQN2ZYNDcjs.detectCadence; exports.detectCadences = _chunk4VZ5MZAMcjs.detectCadences; exports.detectChord = _chunkKQN2ZYNDcjs.detectChord; exports.detectChordBest = _chunkKQN2ZYNDcjs.detectChordBest; exports.detectKey = _chunkKQN2ZYNDcjs.detectKey; exports.detectKeyBest = _chunkKQN2ZYNDcjs.detectKeyBest; exports.detectKeyFromNotes = _chunkKQN2ZYNDcjs.detectKeyFromNotes; exports.functionOf = _chunkKQN2ZYNDcjs.functionOf; exports.isBorrowedChord = _chunkKQN2ZYNDcjs.isBorrowedChord; exports.isDiatonic = _chunkKQN2ZYNDcjs.isDiatonic; exports.isMinorKey = _chunkKQN2ZYNDcjs.isMinorKey; exports.parallelKey = _chunkKQN2ZYNDcjs.parallelKey; exports.romanToChord = _chunkKQN2ZYNDcjs.romanToChord; exports.secondaryDominant = _chunkKQN2ZYNDcjs.secondaryDominant; exports.tensionCurve = _chunk4VZ5MZAMcjs.tensionCurve; exports.tensionCurveFrom = _chunk4VZ5MZAMcjs.tensionCurveFrom; exports.toVoiceNotes = _chunk4VZ5MZAMcjs.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"}