@libraz/libcantus 0.9.4 → 0.9.5

package/README.md

@@ -1,9 +1,16 @@
 # @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 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.
 
 [![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)
@@ -21,7 +28,7 @@ dependencies.
   (`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
+- **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.
@@ -29,17 +36,18 @@ dependencies.
   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
+- **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 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.
+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.
 
 ## Install
 
@@ -88,11 +96,11 @@ pure functions, so the two styles interoperate freely. The same task with the
 functional API:
 
 ```ts
-import { chordFromDegree, chordPitchClasses, classifyInterval, majorKey } from '@libraz/libcantus';
+import { chordFromDegree, chordPitchClasses, classifyInterval, ConsonanceClass, majorKey } from '@libraz/libcantus';
 
 const cMajor = majorKey(0);
 
-classifyInterval(7); // IntervalQuality.PerfectConsonance
+classifyInterval(7); // ConsonanceClass.PerfectConsonance
 chordPitchClasses(chordFromDegree(4, 'dom7', cMajor)); // [2, 5, 7, 11]  (G7)
 ```
 
@@ -160,7 +168,7 @@ Chord.of('F', 'min').analyze(Key.major('C'));
 // { function: 'subdominant', borrowed: true, source: 'parallelMinor', roman: 'iv' }
 ```
 
-## Recognize what you hear
+## Recognize chords and keys
 
 Notes in, chord or key out — the inverse of the builders:
 
@@ -256,10 +264,11 @@ 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
+## Analyze and extend an arrangement
 
-The arrangement layer takes raw multi-track `NoteEvent`s, recovers the harmony,
-then analyses and generates against it:
+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 {

package/README_ja.md

@@ -0,0 +1,268 @@
+# @libraz/libcantus
+
+TypeScript だけで書かれた音楽理論エンジンです。MIDI ノート番号とコードネームを受け取り、和声的な意味（ローマ数字、和声機能、終止、キー）を返します。さらにその解析結果を土台にして新しいパートを生成します。DAW の隣に置くツール（解析器、ジェネレーター、作曲アシスタント）で使うことを想定しています。
+
+扱うのは理論の層だけで、I/O やオーディオには踏み込みません。MIDI ファイルの読み書き、オーディオ解析、再生のいずれも持たないので、パースは呼び出し側で行い、ノートイベントとして渡してください。実行時依存はありません。その層も必要であれば、[libsonare](https://github.com/libraz/libsonare) が音声解析・マスタリング・音源合成・SMF の読み書きを担当していて、npm パッケージなので本ライブラリと並べて置けます。両者はコードを共有しておらず、どちらも単独で使えます。
+
+[![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/)
+[![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 });
+```
+
+## 和声を解析する
+
+コードを、和声機能・終止・モーダルインターチェンジつきのローマ数字解析に変換します。長調と短調の双方に対応し、転回形も反映されます。
+
+```ts
+import { Chord, Key } from '@libraz/libcantus';
+
+// 長調に現れる短調の iv は、借用されたサブドミナントとして解釈される:
+Chord.of('F', 'min').analyze(Key.major('C'));
+// { function: 'subdominant', borrowed: true, source: 'parallelMinor', roman: 'iv' }
+```
+
+## コードとキーを判定する
+
+ノートを入れるとコードやキーが返ります。組み立てとちょうど逆方向の処理です。
+
+```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 メジャー  (キーのランキングは関数として提供)
+```
+
+## コードとスケールを綴る
+
+`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']
+```
+
+## リハーモナイズする
+
+クラス側ではネガティブハーモニーによる反転を、関数側では代理コードの候補（裏コード、平行調、借用、クロマチックメディアント、およびモーダルインターチェンジのパレット）の列挙を扱います。
+
+```ts
+import { Chord, Key, majorKey, parseChordSymbol, substituteChord } from '@libraz/libcantus';
+
+Key.major('C').chord(4, 'dom7').negativeHarmony().symbol(); // 'Dm7b5'
+
+// 代理コードやパレットの検索はリストを返すので関数として提供される:
+substituteChord(parseChordSymbol('G7'), majorKey(0));
+// [{ chord: Db7, type: 'tritone', ... }, ...]
+```
+
+## スケールとテンションを選ぶ
+
+クラス側で、あるコードに使えるスケールと、そこで利用できるテンションおよびアボイドノートを求められます。`scalesForChanges` を使えば、コード進行全体を通して繋がりが最適になるスケール選択が得られます。
+
+```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 はアボイドノート)
+```
+
+## コードをボイシングする
+
+進行全体を、声部の動きが最小になる 4 声（SATB）の MIDI ボイシングに展開できます。単体のコードをコンピングスタイル（drop-2/3、シェル、ルートレス）でボイシングすることもできます。
+
+```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` の述語群（並行・隠伏の完全音程、音域の間隔、声部の交差、導音の解決など）を使います。
+
+## パートを生成する
+
+旋律と伴奏のジェネレーターは、いずれもシードを取り決定的に動きます。
+
+```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 — 決定的に生成された短い旋律の断片
+```
+
+`humanize`, `extractGrooveTemplate`, `applyGrooveTemplate` は拍子を踏まえたノリを付け足します。ある演奏のノリを取り出して別の演奏に移植する使い方もできます。
+
+## アレンジを解析して足す
+
+アレンジ層は、DAW や MIDI ファイルのパーサーが吐いたマルチトラックの `NoteEvent` をそのまま受け取り、和声を復元してから解析と生成を行います。
+
+```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' });
+```
+
+`harmonizeMelody` は逆方向を担当します。旋律だけを渡すと、それを和声づけするのに最適なキー・移調量・コードの経路を（必要ならリハーモナイズも含めて）探索します。
+
+アレンジ層と生成層のあいだでやり取りするノートイベントは `NoteEvent`（`{ pitch, startBeat, durationBeat, velocity? }`。音高は MIDI ノート番号、時間は 4 分音符を 1 とする拍数）の一種類に統一されています。シードを取るジェネレーター（`bass`, `groove`, `countermelody`, `rhythm`, `drums`, `motif`, `progression`）は、同じシードに対して常に同じ結果を返します。
+
+## 音高を音響として扱う
+
+周波数、セント、EDO、純正律を扱えます。音律の設計、微分音、そして解析に使えます。
+
+```ts
+import { frequencyOf, edo, justDeviationCents } from '@libraz/libcantus';
+```
+
+拍子まわりのヘルパー（`TimeSignature`, `parseTimeSignature`, `beatsPerBar`, `metricWeight`, `isStrongBeat`, `tuplet`）は単純拍子と複合拍子の両方を扱い、アクセントを考慮するジェネレーター群の土台にもなっています。
+
+## ドキュメント
+
+すべてのエクスポートをシグネチャつきで、領域ごとに分類し、動かせる例を添えた API リファレンスをソースから生成して **[libraz.github.io/libcantus](https://libraz.github.io/libcantus/)** に公開しています。
+
+## ライセンス
+
+Apache-2.0

package/dist/analyze/index.cjs

@@ -7,8 +7,8 @@
 
 
 
-var _chunkRC6GBMCDcjs = require('../chunk-RC6GBMCD.cjs');
-require('../chunk-36N73KZ3.cjs');
+var _chunk4VZ5MZAMcjs = require('../chunk-4VZ5MZAM.cjs');
+require('../chunk-2A2QMA74.cjs');
 
 
 
@@ -26,12 +26,12 @@ require('../chunk-36N73KZ3.cjs');
 
 
 
-var _chunkCAN76NCUcjs = require('../chunk-CAN76NCU.cjs');
+var _chunkKQN2ZYNDcjs = require('../chunk-KQN2ZYND.cjs');
 
 
-var _chunkQ6OP4U43cjs = require('../chunk-Q6OP4U43.cjs');
-require('../chunk-FNDWXRRI.cjs');
-require('../chunk-7MGZ7D62.cjs');
+var _chunkWFDXOLUBcjs = require('../chunk-WFDXOLUB.cjs');
+require('../chunk-BSLTLGM3.cjs');
+require('../chunk-PI3UXRWK.cjs');
 
 
 
@@ -58,5 +58,5 @@ require('../chunk-7MGZ7D62.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.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;
 //# sourceMappingURL=index.cjs.map

package/dist/analyze/index.d.cts

@@ -1,102 +1,12 @@
 import { T as TimeSignature } from '../index-DXd9JikN.cjs';
-import { K as KeyScale, N as NoteEvent } from '../types-BN6_Q9Kl.cjs';
-import { C as Chord, d as ChordToneRole } from '../index-y_ak9_Hi.cjs';
-export { a as ChordQuality, b as ChordSegment, c as ChordSpan, P as PitchSpelling } from '../index-y_ak9_Hi.cjs';
-import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-tJhkmQgE.cjs';
-import { a as ChordTimeline, C as CadenceHit } from '../index-Be74mcon.cjs';
-export { b as ChordTimelineOptions, c as ChordTimelineResult, d as chordTimelineFromChords, e as chordTimelineFromNotes, f as detectCadences } from '../index-Be74mcon.cjs';
-export { C as ChordMatch, D as DetectChordOptions, a as DetectKeyOptions, K as KeyMatch, b as KeyVariant, d as detectChord, c as detectChordBest, e as detectKey, f as detectKeyBest, g as detectKeyFromNotes } from '../index-BtXT6UQ0.cjs';
-export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from '../function-DNugAOrt.cjs';
-
-/**
- * Roman-numeral parsing and formatting.
- *
- * The {@link ROMAN_STYLE} table is the single source of truth for both
- * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
- * inverses by construction.
- */
-
-/**
- * Build the chord denoted by a Roman numeral in a key.
- *
- * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
- * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
- * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
- * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
- * whose root becomes a local major tonic for the applied chord. Inverted chords
- * carry a `bassPc`.
- *
- * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
- * `m7b5`), since no half-diminished triad exists. Extension and added-tone
- * suffixes are the canonical case-sensitive forms emitted by
- * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
- * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
- * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
- * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
- * A figure string that is neither a recognized inversion nor a supported
- * quality suffix throws rather than silently degrading to a triad.
- *
- * @param text The Roman numeral.
- * @param key The prevailing key.
- * @returns The chord.
- * @example
- * ```ts
- * import { romanToChord, majorKey } from '@libraz/libcantus';
- * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
- * ```
- * @category Functional Harmony
- */
-declare function romanToChord(text: string, key: KeyScale): Chord;
-/**
- * Options for {@link chordToRoman}.
- *
- * @category Functional Harmony
- */
-type ChordToRomanOptions = {
-    /**
-     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
-     * instead of naming its root against the home key (`II7`, `#ivo7`).
-     *
-     * Off by default: naming the root is always a correct spelling, whereas
-     * whether a chromatic dominant is genuinely applied is a reading only the
-     * caller can make. Turning it on makes {@link chordToRoman} the exact inverse
-     * of {@link romanToChord} for the chords {@link secondaryDominant} builds.
-     */
-    applied?: boolean;
-};
-/**
- * Render a chord as a Roman numeral relative to a key.
- *
- * Diatonic roots take their scale-degree numeral directly, so numerals are
- * correct in both major and minor keys (and any custom scale). The quality
- * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
- * convention. A key that is not heptatonic has no numeral of its own for every
- * degree, so its roots are named against its parallel major.
- *
- * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
- * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
- * chords; added-tone and extended qualities have no lossless figure and render
- * in root position instead (the bass is dropped, pitch classes are preserved).
- *
- * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
- * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
- * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
- * is no unambiguous way to write such a bass; a caller that must keep it should
- * read `chord.bassPc` alongside the numeral.
- *
- * @param chord The chord to name.
- * @param key The prevailing key.
- * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals.
- * @returns The Roman numeral string.
- * @example
- * ```ts
- * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
- * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
- * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
- * ```
- * @category Functional Harmony
- */
-declare function chordToRoman(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): string;
+import { N as NoteEvent, K as KeyScale } from '../types-BN6_Q9Kl.cjs';
+import { d as ChordToneRole, C as Chord } from '../index-oTQbYYIs.cjs';
+export { a as ChordQuality, b as ChordSegment, c as ChordSpan, P as PitchSpelling } from '../index-oTQbYYIs.cjs';
+import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-B2Ulxxpo.cjs';
+import { a as ChordTimeline, C as CadenceHit } from '../index-BkYJ0xMq.cjs';
+export { b as ChordTimelineOptions, c as ChordTimelineResult, d as chordTimelineFromChords, e as chordTimelineFromNotes, f as detectCadences } from '../index-BkYJ0xMq.cjs';
+export { C as ChordMatch, D as DetectChordOptions, a as DetectKeyOptions, K as KeyMatch, b as KeyVariant, d as detectChord, c as detectChordBest, e as detectKey, f as detectKeyBest, g as detectKeyFromNotes } from '../index-alrRninU.cjs';
+export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, b as ChordToRomanOptions, H as HarmonicFunction, c as analyzeChord, d as borrowedSource, e as chordToRoman, f as detectCadence, g as functionOf, i as isBorrowedChord, h as isDiatonic, j as isMinorKey, p as parallelKey, r as romanToChord, s as secondaryDominant } from '../function-CxixTB02.cjs';
 
 /**
  * A suspension figure, named by the interval above the bass and the interval it
@@ -498,4 +408,4 @@ declare function tensionCurveFrom(tracks: ArrangementTrack[], analysis: Arrangem
     step?: number;
 }): TensionPoint[];
 
-export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, Chord as ChordData, ChordTimeline, type ChordToRomanOptions, ChordToneRole, type Conflict, type IdentifiedVoiceNote, KeyScale, NoteEvent, NoteSafety, SafetyProfile, type SuspensionFigure, type TensionPoint, type TheoryLabel, TimeSignature, type TrackAnalysis, type TrackRole, type VoiceNote, VoiceSnapshot, analyzeArrangement, analyzeVoice, chordToRoman, romanToChord, tensionCurve, tensionCurveFrom, toVoiceNotes };
+export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, Chord as ChordData, ChordTimeline, ChordToneRole, type Conflict, type IdentifiedVoiceNote, KeyScale, NoteEvent, NoteSafety, SafetyProfile, type SuspensionFigure, type TensionPoint, type TheoryLabel, TimeSignature, type TrackAnalysis, type TrackRole, type VoiceNote, VoiceSnapshot, analyzeArrangement, analyzeVoice, tensionCurve, tensionCurveFrom, toVoiceNotes };

package/dist/analyze/index.d.ts

@@ -1,102 +1,12 @@
 import { T as TimeSignature } from '../index-DXd9JikN.js';
-import { K as KeyScale, N as NoteEvent } from '../types-BN6_Q9Kl.js';
-import { C as Chord, d as ChordToneRole } from '../index-C83mZI1P.js';
-export { a as ChordQuality, b as ChordSegment, c as ChordSpan, P as PitchSpelling } from '../index-C83mZI1P.js';
-import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-6VR8-kit.js';
-import { a as ChordTimeline, C as CadenceHit } from '../index-C5UBbQ4G.js';
-export { b as ChordTimelineOptions, c as ChordTimelineResult, d as chordTimelineFromChords, e as chordTimelineFromNotes, f as detectCadences } from '../index-C5UBbQ4G.js';
-export { C as ChordMatch, D as DetectChordOptions, a as DetectKeyOptions, K as KeyMatch, b as KeyVariant, d as detectChord, c as detectChordBest, e as detectKey, f as detectKeyBest, g as detectKeyFromNotes } from '../index-70p168VM.js';
-export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from '../function-BtiZb9i9.js';
-
-/**
- * Roman-numeral parsing and formatting.
- *
- * The {@link ROMAN_STYLE} table is the single source of truth for both
- * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
- * inverses by construction.
- */
-
-/**
- * Build the chord denoted by a Roman numeral in a key.
- *
- * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
- * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
- * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
- * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
- * whose root becomes a local major tonic for the applied chord. Inverted chords
- * carry a `bassPc`.
- *
- * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
- * `m7b5`), since no half-diminished triad exists. Extension and added-tone
- * suffixes are the canonical case-sensitive forms emitted by
- * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
- * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
- * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
- * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
- * A figure string that is neither a recognized inversion nor a supported
- * quality suffix throws rather than silently degrading to a triad.
- *
- * @param text The Roman numeral.
- * @param key The prevailing key.
- * @returns The chord.
- * @example
- * ```ts
- * import { romanToChord, majorKey } from '@libraz/libcantus';
- * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
- * ```
- * @category Functional Harmony
- */
-declare function romanToChord(text: string, key: KeyScale): Chord;
-/**
- * Options for {@link chordToRoman}.
- *
- * @category Functional Harmony
- */
-type ChordToRomanOptions = {
-    /**
-     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
-     * instead of naming its root against the home key (`II7`, `#ivo7`).
-     *
-     * Off by default: naming the root is always a correct spelling, whereas
-     * whether a chromatic dominant is genuinely applied is a reading only the
-     * caller can make. Turning it on makes {@link chordToRoman} the exact inverse
-     * of {@link romanToChord} for the chords {@link secondaryDominant} builds.
-     */
-    applied?: boolean;
-};
-/**
- * Render a chord as a Roman numeral relative to a key.
- *
- * Diatonic roots take their scale-degree numeral directly, so numerals are
- * correct in both major and minor keys (and any custom scale). The quality
- * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
- * convention. A key that is not heptatonic has no numeral of its own for every
- * degree, so its roots are named against its parallel major.
- *
- * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
- * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
- * chords; added-tone and extended qualities have no lossless figure and render
- * in root position instead (the bass is dropped, pitch classes are preserved).
- *
- * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
- * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
- * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
- * is no unambiguous way to write such a bass; a caller that must keep it should
- * read `chord.bassPc` alongside the numeral.
- *
- * @param chord The chord to name.
- * @param key The prevailing key.
- * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals.
- * @returns The Roman numeral string.
- * @example
- * ```ts
- * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
- * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
- * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
- * ```
- * @category Functional Harmony
- */
-declare function chordToRoman(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): string;
+import { N as NoteEvent, K as KeyScale } from '../types-BN6_Q9Kl.js';
+import { d as ChordToneRole, C as Chord } from '../index-COw1Ky9g.js';
+export { a as ChordQuality, b as ChordSegment, c as ChordSpan, P as PitchSpelling } from '../index-COw1Ky9g.js';
+import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-BuaB-ypt.js';
+import { a as ChordTimeline, C as CadenceHit } from '../index-DRtIhlJj.js';
+export { b as ChordTimelineOptions, c as ChordTimelineResult, d as chordTimelineFromChords, e as chordTimelineFromNotes, f as detectCadences } from '../index-DRtIhlJj.js';
+export { C as ChordMatch, D as DetectChordOptions, a as DetectKeyOptions, K as KeyMatch, b as KeyVariant, d as detectChord, c as detectChordBest, e as detectKey, f as detectKeyBest, g as detectKeyFromNotes } from '../index-CAN7v-kw.js';
+export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, b as ChordToRomanOptions, H as HarmonicFunction, c as analyzeChord, d as borrowedSource, e as chordToRoman, f as detectCadence, g as functionOf, i as isBorrowedChord, h as isDiatonic, j as isMinorKey, p as parallelKey, r as romanToChord, s as secondaryDominant } from '../function-DTCt675z.js';
 
 /**
  * A suspension figure, named by the interval above the bass and the interval it
@@ -498,4 +408,4 @@ declare function tensionCurveFrom(tracks: ArrangementTrack[], analysis: Arrangem
     step?: number;
 }): TensionPoint[];
 
-export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, Chord as ChordData, ChordTimeline, type ChordToRomanOptions, ChordToneRole, type Conflict, type IdentifiedVoiceNote, KeyScale, NoteEvent, NoteSafety, SafetyProfile, type SuspensionFigure, type TensionPoint, type TheoryLabel, TimeSignature, type TrackAnalysis, type TrackRole, type VoiceNote, VoiceSnapshot, analyzeArrangement, analyzeVoice, chordToRoman, romanToChord, tensionCurve, tensionCurveFrom, toVoiceNotes };
+export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, Chord as ChordData, ChordTimeline, ChordToneRole, type Conflict, type IdentifiedVoiceNote, KeyScale, NoteEvent, NoteSafety, SafetyProfile, type SuspensionFigure, type TensionPoint, type TheoryLabel, TimeSignature, type TrackAnalysis, type TrackRole, type VoiceNote, VoiceSnapshot, analyzeArrangement, analyzeVoice, tensionCurve, tensionCurveFrom, toVoiceNotes };