@libraz/libcantus 1.2.0 → 1.4.0

package/NOTICE

@@ -0,0 +1,63 @@
+libcantus
+Copyright the libcantus authors
+
+This product includes software developed as part of the libcantus project,
+licensed under the Apache License, Version 2.0. See LICENSE.
+
+--------------------------------------------------------------------------------
+
+Third-party assets
+
+The notated figures under docs/images embed glyph outlines (clefs, noteheads,
+accidentals and the brace) taken from the Bravura music font:
+
+  Bravura
+  Copyright (c) 2015 Steinberg Media Technologies GmbH
+  Licensed under the SIL Open Font License, Version 1.1
+  https://github.com/steinbergmedia/bravura
+
+The outlines are embedded as SVG paths so that the figures render without
+loading a font. Bravura itself is not redistributed, and no part of this
+project is licensed under the SIL Open Font License.
+
+--------------------------------------------------------------------------------
+
+Math.log2, Math.exp and Math.pow (src/js/ieee754.cpp)
+
+src/js/ieee754.cpp is ported from V8's src/base/ieee754.cc (tag 12.4.254.21),
+which is adapted from fdlibm and FreeBSD msun:
+
+  Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.
+
+  Developed at SunSoft, a Sun Microsystems, Inc. business.
+  Permission to use, copy, modify, and distribute this
+  software is freely granted, provided that this notice
+  is preserved.
+
+  Copyright 2016 the V8 project authors. All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are
+  met:
+
+      * Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer.
+      * Redistributions in binary form must reproduce the above
+        copyright notice, this list of conditions and the following
+        disclaimer in the documentation and/or other materials provided
+        with the distribution.
+      * Neither the name of Google Inc. nor the names of its
+        contributors may be used to endorse or promote products derived
+        from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -10,7 +10,7 @@ Pure-TypeScript music theory for MIDI note events. Recover the harmony from note
 [![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/)
 
-![From note events to parts, and back](docs/images/pipeline.svg)
+![From note events to parts, and back](https://raw.githubusercontent.com/libraz/libcantus/main/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.
 
@@ -35,6 +35,10 @@ Composer.of({ key: chords.key, bpm: 120, seed: 1 }).bass(chords, { style: 'walki
 
 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.
 
+Another piece is read the same way and measured against the first dimension by dimension — form, harmony, motif derivation, rhythm — never folded into one score: `analyzeReference` compresses a piece into a portable profile, and `compareReferences` reads two of them against each other.
+
+That same profile doubles as a target for new material: `deriveCompositionPlan` turns it into a `CompositionPlan` — form, harmony and a motif derivation forest stated as instructions a generator can follow exactly — and `generateMelody` writes a melody to it, with `evaluateComposition` reading the result back against the plan. See [Generating from a reference](https://github.com/libraz/libcantus/blob/main/docs/en/generation.md#generating-from-a-reference).
+
 ## Use cases
 
 | Use case | What it does | Worked guide |
@@ -57,6 +61,8 @@ yarn add @libraz/libcantus
 
 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.
 
+This package is the TypeScript reference implementation, synchronous and dependency-free. The same API is also available from a C++ core through WebAssembly, Python and a command-line tool; see [the repository](https://github.com/libraz/libcantus) and [Packages](https://github.com/libraz/libcantus/blob/main/docs/en/packages.md).
+
 ## Documentation
 
 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.

package/README_ja.md

@@ -10,7 +10,7 @@ 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)
+![ノートイベントからパートへ、そして再びノートイベントへ](https://raw.githubusercontent.com/libraz/libcantus/main/docs/images/pipeline-ja.svg)
 
 このライブラリは、すでにノートやコード記号を持っているソフトウェア（DAW のプロジェクト、MIDI パーサー、練習支援ツールなど）と、その音が和声的に何を意味するかとの間を埋めます。ノートイベントを渡すと和声が求まり、ジェネレーターはいま読み取ったその和声に沿ってパートを書きます。
 
@@ -35,17 +35,21 @@ Composer.of({ key: chords.key, bpm: 120, seed: 1 }).bass(chords, { style: 'walki
 
 コードの境界は決め打ちせずに探索し、キーも同様に探します。転調する曲を、冒頭のキーのまま読み続けることはありません。答えには根拠が伴います。コード分析・終止・ローマ数字はいずれも `rationale` と、退けた候補を併せて返し、入力だけでは決まらない項目は、もっともらしい推測ではなく `null` を返します。
 
+もう1曲も同じように読み取り、フォーム・和声・モチーフの派生・リズムを次元ごとに比較できます。単一のスコアにまとめることはありません。`analyzeReference` が曲を持ち運び可能なプロファイルに圧縮し、`compareReferences` がその2つを突き合わせます。
+
+そのプロファイルは、新しい素材を書くための目標にもなります。`deriveCompositionPlan` はプロファイルを `CompositionPlan` に変換します。フォーム・和声・モチーフの派生の森を、ジェネレータがそのまま辿れる指示として持つ値です。`generateMelody` はその計画に沿って旋律を書き、`evaluateComposition` は結果を計画に照らして読み返します。[リファレンスからの生成](https://github.com/libraz/libcantus/blob/main/docs/ja/generation.md#リファレンスからの生成)を参照してください。
+
 ## ユースケース
 
 | ユースケース | 内容 | 実例のガイド |
 |---|---|---|
-| 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) |
+| DAW のアシスタント | トラックから和声を読み取り、それに沿ってベースラインを書く。 | [DAW ワークフロー](https://github.com/libraz/libcantus/blob/main/docs/ja/use-cases/daw-workflow.md) |
+| 楽曲アナライザー | 1 つのスコアから調区間、終止形、和声的な還元、フレーズ、セクション、モチーフを得る。 | [楽曲の解析](https://github.com/libraz/libcantus/blob/main/docs/ja/use-cases/piece-analysis.md) |
+| 転調レポート | 転調を、軸和音・確信度・調同士の関係とともに提示する。 | [転調レポート](https://github.com/libraz/libcantus/blob/main/docs/ja/use-cases/modulation-report.md) |
+| 和声課題のチェッカー | 声部書法と種目対位法の違反を、違反した声部と破った規則つきで報告する。 | [和声課題のチェック](https://github.com/libraz/libcantus/blob/main/docs/ja/use-cases/harmony-exercise-checker.md) |
+| 自動生成アレンジ | シードを固定した 1 つのコンポーザーがコード進行・各パート・ドラムを書き、演奏可能性を確認する。 | [生成によるアレンジ](https://github.com/libraz/libcantus/blob/main/docs/ja/use-cases/generative-arrangement.md) |
+| コード譜の取り込み | 打ち込んだコード記号をタイムライン、ヴォイシング、ベースラインに変換する。 | [コード譜の取り込み](https://github.com/libraz/libcantus/blob/main/docs/ja/use-cases/chord-chart-import.md) |
+| パート譜の準備 | パートを楽器に合わせ、その奏者が読む音高で書き出す。 | [パート譜の準備](https://github.com/libraz/libcantus/blob/main/docs/ja/use-cases/part-preparation.md) |
 
 ## インストール
 
@@ -57,11 +61,13 @@ yarn add @libraz/libcantus
 
 パッケージのルートから API 全体を公開しています。`@libraz/libcantus/core`、`/theory`、`/analyze`、`/generate`、`/model` は同じシンボル群に対する、より狭い読み込み境界です。いずれのパスも ESM と CommonJS の両方のビルドを同梱しています。
 
+このパッケージは TypeScript によるリファレンス実装で、同期 API であり、依存パッケージはありません。同じ API は C++ コアを使う WebAssembly、Python、コマンドラインツールからも使えます。詳しくは[リポジトリ](https://github.com/libraz/libcantus)と[パッケージ構成](https://github.com/libraz/libcantus/blob/main/docs/ja/packages.md)を参照してください。
+
 ## ドキュメント
 
-音楽理論にはじめて触れる場合は、[入門ガイド](docs/ja/primer/index.md)から始めてください。この API が土台にしている考え方 — 音高と音程、音階と調、和音、和声、声部、リズムと拍子 — を、楽譜ではなく TypeScript を書く読者に向けて説明しています。
+音楽理論にはじめて触れる場合は、[入門ガイド](https://github.com/libraz/libcantus/blob/main/docs/ja/primer/index.md)から始めてください。この API が土台にしている考え方 — 音高と音程、音階と調、和音、和声、声部、リズムと拍子 — を、楽譜ではなく TypeScript を書く読者に向けて説明しています。
 
-そうでなければ、[はじめに](docs/ja/introduction.md)と[使いはじめる](docs/ja/getting-started.md)から読んでください。各分野のガイドとリファレンスはそこから辿れます。ガイド中の `ts` の例はすべてテストスイートで実行され、行末コメントがリテラルを名指していれば（em ダッシュに続けて理由が書かれていてもかまいません）実際の戻り値と照合されます。
+そうでなければ、[はじめに](https://github.com/libraz/libcantus/blob/main/docs/ja/introduction.md)と[使いはじめる](https://github.com/libraz/libcantus/blob/main/docs/ja/getting-started.md)から読んでください。各分野のガイドとリファレンスはそこから辿れます。ガイド中の `ts` の例はすべてテストスイートで実行され、行末コメントがリテラルを名指していれば（em ダッシュに続けて理由が書かれていてもかまいません）実際の戻り値と照合されます。
 
 ## できないこと
 
@@ -70,7 +76,7 @@ yarn add @libraz/libcantus
 - **旋法体系そのものは扱いません。** `WORLD_SCALES` が記録するのは、その伝統が名前を与えている音の素材 — ターット、マカームの音組織、日本の五音音階 — であって、その上に築かれた語法ではありません。
 - **コーパスは同梱しません。** 統計を取るためのデータは含みません。
 
-残りは[疑問と制限](docs/ja/faq.md)にまとめています。機能和声の読みが適用できない場合や、エンジンが推測しないことについてもそこで扱います。
+残りは[疑問と制限](https://github.com/libraz/libcantus/blob/main/docs/ja/faq.md)にまとめています。機能和声の読みが適用できない場合や、エンジンが推測しないことについてもそこで扱います。
 
 ## ライセンス
 

package/dist/analyze/index.cjs

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkHWHGOVO6cjs = require('../chunk-HWHGOVO6.cjs');
+var _chunkE3QO3UETcjs = require('../chunk-E3QO3UET.cjs');
 
 
 
@@ -13,12 +13,12 @@ var _chunkHWHGOVO6cjs = require('../chunk-HWHGOVO6.cjs');
 
 
 
+var _chunk3MDOEFIQcjs = require('../chunk-3MDOEFIQ.cjs');
 
 
 
 
 
-var _chunkHPVSH7SFcjs = require('../chunk-HPVSH7SF.cjs');
 
 
 
@@ -52,12 +52,8 @@ var _chunkHPVSH7SFcjs = require('../chunk-HPVSH7SF.cjs');
 
 
 
-var _chunkSGLEQVJHcjs = require('../chunk-SGLEQVJH.cjs');
-require('../chunk-35NBV2FT.cjs');
 
 
-var _chunk3R3QVKY5cjs = require('../chunk-3R3QVKY5.cjs');
-require('../chunk-S5BKZZGM.cjs');
 
 
 
@@ -68,8 +64,12 @@ require('../chunk-S5BKZZGM.cjs');
 
 
 
+var _chunkLQZQDBCDcjs = require('../chunk-LQZQDBCD.cjs');
+require('../chunk-KMYGRFZ6.cjs');
 
 
+var _chunkYDGMWH43cjs = require('../chunk-YDGMWH43.cjs');
+require('../chunk-S3QELJUE.cjs');
 
 
 
@@ -109,5 +109,29 @@ require('../chunk-S5BKZZGM.cjs');
 
 
 
-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;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.CADENCE_TYPES = _chunkLQZQDBCDcjs.CADENCE_TYPES; exports.HARMONIC_FUNCTIONS = _chunkLQZQDBCDcjs.HARMONIC_FUNCTIONS; exports.MELODIC_CONTOUR_SHAPES = _chunkLQZQDBCDcjs.MELODIC_CONTOUR_SHAPES; exports.MODAL_SCALE_NAMES = _chunkLQZQDBCDcjs.MODAL_SCALE_NAMES; exports.MOTIF_RELATION_KINDS = _chunkLQZQDBCDcjs.MOTIF_RELATION_KINDS; exports.NoteSafety = _chunkYDGMWH43cjs.NoteSafety; exports.REDUCTION_LEVELS = _chunkLQZQDBCDcjs.REDUCTION_LEVELS; exports.REFERENCE_PROFILE_VERSION = _chunkLQZQDBCDcjs.REFERENCE_PROFILE_VERSION; exports.RHYTHM_IOI_BINS = _chunkLQZQDBCDcjs.RHYTHM_IOI_BINS; exports.analyzeArrangement = _chunk3MDOEFIQcjs.analyzeArrangement; exports.analyzeChord = _chunkLQZQDBCDcjs.analyzeChord; exports.analyzePolyphony = _chunk3MDOEFIQcjs.analyzePolyphony; exports.analyzeReference = _chunk3MDOEFIQcjs.analyzeReference; exports.analyzeRhythm = _chunkLQZQDBCDcjs.analyzeRhythm; exports.analyzeVoice = _chunkLQZQDBCDcjs.analyzeVoice; exports.assertChordTimeline = _chunkLQZQDBCDcjs.assertChordTimeline; exports.assertReferenceProfile = _chunkLQZQDBCDcjs.assertReferenceProfile; exports.augmentedSixthChord = _chunkLQZQDBCDcjs.augmentedSixthChord; exports.augmentedSixthFromPitchClasses = _chunkLQZQDBCDcjs.augmentedSixthFromPitchClasses; exports.augmentedSixthKind = _chunkLQZQDBCDcjs.augmentedSixthKind; exports.borrowedSource = _chunkLQZQDBCDcjs.borrowedSource; exports.chordTimelineFromChords = _chunkLQZQDBCDcjs.chordTimelineFromChords; exports.chordTimelineFromNotes = _chunkLQZQDBCDcjs.chordTimelineFromNotes; exports.chordToRoman = _chunkLQZQDBCDcjs.chordToRoman; exports.compareMelodies = _chunkLQZQDBCDcjs.compareMelodies; exports.compareReferences = _chunk3MDOEFIQcjs.compareReferences; exports.createArrangementSession = _chunk3MDOEFIQcjs.createArrangementSession; exports.detectCadence = _chunkLQZQDBCDcjs.detectCadence; exports.detectCadences = _chunkLQZQDBCDcjs.detectCadences; exports.detectChord = _chunkLQZQDBCDcjs.detectChord; exports.detectChordBest = _chunkLQZQDBCDcjs.detectChordBest; exports.detectKey = _chunkLQZQDBCDcjs.detectKey; exports.detectKeyBest = _chunkLQZQDBCDcjs.detectKeyBest; exports.detectKeyFromNotes = _chunkLQZQDBCDcjs.detectKeyFromNotes; exports.detectModulations = _chunkLQZQDBCDcjs.detectModulations; exports.explainRoman = _chunkLQZQDBCDcjs.explainRoman; exports.extractMotifs = _chunkLQZQDBCDcjs.extractMotifs; exports.functionOf = _chunkLQZQDBCDcjs.functionOf; exports.hypermeter = _chunk3MDOEFIQcjs.hypermeter; exports.isBorrowedChord = _chunkLQZQDBCDcjs.isBorrowedChord; exports.isDiatonic = _chunkLQZQDBCDcjs.isDiatonic; exports.isMinorKey = _chunkLQZQDBCDcjs.isMinorKey; exports.keyTimelineFromNotes = _chunkLQZQDBCDcjs.keyTimelineFromNotes; exports.melodicContour = _chunkLQZQDBCDcjs.melodicContour; exports.melodicSimilarity = _chunkLQZQDBCDcjs.melodicSimilarity; exports.motifFromNotes = _chunkLQZQDBCDcjs.motifFromNotes; exports.motifGraph = _chunkLQZQDBCDcjs.motifGraph; exports.phrasesFromTimeline = _chunk3MDOEFIQcjs.phrasesFromTimeline; exports.pivotChords = _chunkLQZQDBCDcjs.pivotChords; exports.prevailingKeyOf = _chunkLQZQDBCDcjs.prevailingKeyOf; exports.reduceProgression = _chunkLQZQDBCDcjs.reduceProgression; exports.relateMotifs = _chunkLQZQDBCDcjs.relateMotifs; exports.romanToChord = _chunkLQZQDBCDcjs.romanToChord; exports.secondaryDominant = _chunkLQZQDBCDcjs.secondaryDominant; exports.secondaryDominantOf = _chunkLQZQDBCDcjs.secondaryDominantOf; exports.sectionsFromNotes = _chunk3MDOEFIQcjs.sectionsFromNotes; exports.spellAugmentedSixth = _chunkLQZQDBCDcjs.spellAugmentedSixth; exports.spellLine = _chunkE3QO3UETcjs.spellLine; exports.structuralCadences = _chunk3MDOEFIQcjs.structuralCadences; exports.tensionCurve = _chunk3MDOEFIQcjs.tensionCurve; exports.tensionCurveFrom = _chunk3MDOEFIQcjs.tensionCurveFrom; exports.toVoiceNotes = _chunkLQZQDBCDcjs.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;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"}
+{"version":3,"sources":["/home/runner/work/libcantus/libcantus/ts/dist/analyze/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,yDAA8B;AAC9B;AACE;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;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;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,ixHAAC","file":"/home/runner/work/libcantus/libcantus/ts/dist/analyze/index.cjs"}

package/dist/analyze/index.d.cts

@@ -1,13 +1,12 @@
-import { i as NoteLike, h as NoteEvent, g as Note } from '../index-Cy15oTvh.cjs';
-export { a as Articulation, I as IntervalData, c as IntervalQualityLabel, e as KeyScale, S as SpelledInterval } from '../index-Cy15oTvh.cjs';
-export { M as MeterChange, b as MeterLike, c as MeterMap, T as TimeSignature } from '../index-BMweUlm5.cjs';
-import { r as SpelledKeyLike } from '../coerce-DRERzdve.cjs';
-export { b as ChordData, c as ChordLike, d as ChordQuality, e as ChordSegment, g as ChordSpan, i as ChordToneRole, K as KeyLike, j as KeyRelation, k as KeyVariant, N as NoteSafety, l as PitchSpelling, n as ResolvedKey, o as SafetyProfile, s as SpelledKeyScale, V as VoiceSnapshot } from '../coerce-DRERzdve.cjs';
-export { r as ScaleName } from '../masks-pADfTOiD.cjs';
-import { e as ChordTimeline } from '../index-BBWNZS0f.cjs';
-export { A as AnalyzeChordOptions, a as AnalyzedNote, B as BorrowedSource, C as CadenceHit, b as CadenceResult, c as ChordAnalysis, d as ChordSegmentation, f as ChordTimelineOptions, g as ChordTimelineResult, h as ChordToRomanOptions, D as DetectCadenceOptions, E as ExplainRomanOptions, H as HarmonicFunction, I as IdentifiedVoiceNote, K as KeyContext, i as KeyProfileName, j as KeyProfilePair, k as KeyRegion, l as KeyTimelineOptions, P as PivotChord, R as RejectedCandidate, m as RomanExplanation, S as SuspensionFigure, T as TheoryLabel, V as VoiceNote, n as analyzeChord, o as analyzeVoice, p as assertChordTimeline, q as borrowedSource, r as chordTimelineFromChords, s as chordTimelineFromNotes, t as chordToRoman, u as detectCadence, v as detectCadences, w as detectModulations, x as explainRoman, y as functionOf, z as isBorrowedChord, F as isDiatonic, G as isMinorKey, J as keyTimelineFromNotes, L as pivotChords, M as prevailingKeyOf, N as romanToChord, O as secondaryDominant, Q as secondaryDominantOf, U as toVoiceNotes } from '../index-BBWNZS0f.cjs';
-import { m as MelodicPhrase } from '../index-DGCNKAUr.cjs';
-export { A as ArrangementAnalysis, a as ArrangementOptions, b as ArrangementSession, c as ArrangementTrack, d as AugmentedSixthKind, C as ChordMatch, e as Conflict, f as ConflictPartner, g as ContourDirection, D as DetectChordOptions, h as DetectKeyOptions, E as ExtractMotifsOptions, F as FormSection, i as FormSectionOptions, H as Hypermeter, j as HypermeterOptions, K as KeyMatch, M as MODAL_SCALE_NAMES, k as MelodicContour, l as MelodicContourShape, n as ModalCandidate, o as ModalScaleName, p as MotifData, q as MotifOccurrence, r as MotifRelation, s as MotifRelationKind, P as Phrase, t as PhraseOptions, u as PhraseSignal, R as ReduceProgressionOptions, v as ReducedChord, w as ReductionBasis, x as ReductionLevel, S as StructuralCadence, T as TensionPoint, y as TrackAnalysis, z as TrackEdit, B as TrackRole, G as analyzeArrangement, I as analyzePolyphony, J as augmentedSixthChord, L as augmentedSixthFromPitchClasses, N as augmentedSixthKind, O as createArrangementSession, Q as detectChord, U as detectChordBest, V as detectKey, W as detectKeyBest, X as detectKeyFromNotes, Y as extractMotifs, Z as hypermeter, _ as melodicContour, $ as motifFromNotes, a0 as phrasesFromTimeline, a1 as reduceProgression, a2 as relateMotifs, a3 as sectionsFromNotes, a4 as spellAugmentedSixth, a5 as structuralCadences, a6 as tensionCurve, a7 as tensionCurveFrom } from '../index-DGCNKAUr.cjs';
+import { i as NoteLike, h as NoteEvent, g as Note } from '../index-C9MYbuKS.cjs';
+export { a as Articulation, I as IntervalData, c as IntervalQualityLabel, e as KeyScale, S as SpelledInterval } from '../index-C9MYbuKS.cjs';
+export { M as MeterChange, b as MeterLike, c as MeterMap, T as TimeSignature } from '../index-5VJgKz_Q.cjs';
+import { r as SpelledKeyLike } from '../coerce-Ytt2Eiq9.cjs';
+export { b as ChordData, c as ChordLike, d as ChordQuality, e as ChordSegment, g as ChordSpan, i as ChordToneRole, K as KeyLike, j as KeyRelation, k as KeyVariant, N as NoteSafety, l as PitchSpelling, n as ResolvedKey, o as SafetyProfile, s as SpelledKeyScale, V as VoiceSnapshot } from '../coerce-Ytt2Eiq9.cjs';
+export { r as ScaleName } from '../masks-BnzXnBj0.cjs';
+import { w as MelodicPhrase, a5 as ReferenceProfile, h as ChordTimeline } from '../types-_ofpb2be.cjs';
+export { A as AnalyzeChordOptions, a as AnalyzedNote, B as BarPositionProfile, b as BorrowedSource, C as CADENCE_TYPES, c as CadenceHit, d as CadenceResult, e as CadenceType, f as ChordAnalysis, g as ChordSegmentation, i as ChordTimelineOptions, j as ChordTimelineResult, k as ChordToRomanOptions, l as ContourDirection, D as DetectCadenceOptions, E as ExplainRomanOptions, m as ExtractMotifsOptions, F as FormSection, n as FormSectionOptions, H as HARMONIC_FUNCTIONS, o as HarmonicFunction, I as IdentifiedVoiceNote, K as KeyContext, p as KeyProfileName, q as KeyProfilePair, r as KeyRegion, s as KeyTimelineOptions, M as MELODIC_CONTOUR_SHAPES, t as MOTIF_RELATION_KINDS, u as MelodicContour, v as MelodicContourShape, x as MotifData, y as MotifGraph, z as MotifGraphEdge, G as MotifGraphNode, J as MotifGraphOptions, L as MotifOccurrence, N as MotifRelation, O as MotifRelationKind, P as MotifRelationSummary, Q as PivotChord, R as REDUCTION_LEVELS, S as REFERENCE_PROFILE_VERSION, T as RHYTHM_IOI_BINS, U as ReduceProgressionOptions, V as ReducedChord, W as ReductionBasis, X as ReductionLevel, Y as ReferenceCadence, Z as ReferenceChord, _ as ReferenceForm, $ as ReferenceHarmony, a0 as ReferenceKeyRegion, a1 as ReferenceMelody, a2 as ReferenceMotif, a3 as ReferencePhrase, a4 as ReferencePhraseMelody, a6 as RejectedCandidate, a7 as RhythmAnalysis, a8 as RhythmAnalysisOptions, a9 as RomanExplanation, aa as SuspensionFigure, ab as TheoryLabel, ac as VoiceNote, ad as analyzeChord, ae as analyzeRhythm, af as analyzeVoice, ag as assertChordTimeline, ah as borrowedSource, ai as chordTimelineFromChords, aj as chordTimelineFromNotes, ak as chordToRoman, al as detectCadence, am as detectCadences, an as detectModulations, ao as explainRoman, ap as extractMotifs, aq as functionOf, ar as isBorrowedChord, as as isDiatonic, at as isMinorKey, au as keyTimelineFromNotes, av as melodicContour, aw as motifFromNotes, ax as motifGraph, ay as pivotChords, az as prevailingKeyOf, aA as reduceProgression, aB as relateMotifs, aC as romanToChord, aD as secondaryDominant, aE as secondaryDominantOf, aF as sectionsFromNotes, aG as toVoiceNotes } from '../types-_ofpb2be.cjs';
+export { A as ArrangementAnalysis, a as ArrangementOptions, b as ArrangementSession, c as ArrangementTrack, d as AugmentedSixthKind, C as ChordMatch, e as Conflict, f as ConflictPartner, D as DetectChordOptions, g as DetectKeyOptions, H as Hypermeter, h as HypermeterOptions, K as KeyMatch, M as MODAL_SCALE_NAMES, i as ModalCandidate, j as ModalScaleName, P as Phrase, k as PhraseOptions, l as PhraseSignal, R as ReferenceProfileOptions, S as StructuralCadence, T as TensionPoint, m as TrackAnalysis, n as TrackEdit, o as TrackRole, p as analyzeArrangement, q as analyzePolyphony, r as analyzeReference, s as augmentedSixthChord, t as augmentedSixthFromPitchClasses, u as augmentedSixthKind, v as createArrangementSession, w as detectChord, x as detectChordBest, y as detectKey, z as detectKeyBest, B as detectKeyFromNotes, E as hypermeter, F as phrasesFromTimeline, G as spellAugmentedSixth, I as structuralCadences, J as tensionCurve, L as tensionCurveFrom } from '../profile-BJd1XkPB.cjs';
 
 /**
  * How alike two phrases are, when they stand in no named relation.
@@ -95,6 +94,153 @@ declare function compareMelodies(a: MelodicPhrase, b: MelodicPhrase): MelodicCom
  */
 declare function melodicSimilarity(a: MelodicPhrase, b: MelodicPhrase): number;
 
+/**
+ * Comparing two {@link ReferenceProfile}s dimension by dimension.
+ *
+ * The answer is never folded into one number: each field names the aspect it
+ * measures, so "a different song built the same way" reads as high structural
+ * fields beside a low surface one. Only `melody.surfaceSimilarity` reads the
+ * motifs' intervals; every other field is invariant under transposition, tempo
+ * and a change of motif intervals.
+ */
+
+/**
+ * Options for {@link compareReferences}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceComparisonOptions = {
+    /**
+     * Upper bound on the cells of the progression alignment.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * How alike two profiled pieces are, one field per aspect.
+ *
+ * Every value is in [0, 1] and symmetric in the two profiles. A value is
+ * `null` when neither profile has anything to measure it on, and 0 when only
+ * one does.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceComparison = {
+    /** Formal layout. */
+    form: {
+        /** Likeness of the section-label sequences. */
+        sectionSequenceSimilarity: number | null;
+        /** Likeness of the phrase-length sequences. */
+        phraseLengthSimilarity: number | null;
+    };
+    /** Harmony. */
+    harmony: {
+        /** Likeness of the structural Roman-numeral progressions. */
+        progressionSimilarity: number | null;
+        /** Likeness of how long each harmonic function is held. */
+        functionSimilarity: number | null;
+        /** Likeness of the phrase-by-phrase cadence sequences. */
+        cadenceSimilarity: number | null;
+        /** Likeness of the key plans, read relative to each piece's first key. */
+        keyPlanSimilarity: number | null;
+        /** Likeness of where in the bar the chords change. */
+        harmonicRhythmOnsetSimilarity: number | null;
+        /** Likeness of how often the chords change. */
+        harmonicRhythmDensitySimilarity: number | null;
+    };
+    /** Melody. */
+    melody: {
+        /** Likeness of the motifs' interval content: the one field that reads the surface. */
+        surfaceSimilarity: number | null;
+        /** Likeness of how the motifs derive from one another. */
+        motifStructureSimilarity: number | null;
+        /** Likeness of the phrases' melodic outlines, each scaled by its own range. */
+        contourSimilarity: number | null;
+        /** Likeness of the phrases' registers, each relative to its piece's melodic mean. */
+        registerSimilarity: number | null;
+    };
+    /** Melodic rhythm. */
+    rhythm: {
+        /** Likeness of where in the bar the melody's onsets fall. */
+        onsetSimilarity: number | null;
+        /** Likeness of the melodies' onsets per bar. */
+        densitySimilarity: number | null;
+        /** Likeness of the melodies' inter-onset-interval distributions. */
+        durationSimilarity: number | null;
+        /** Likeness of the melodies' syncopation. */
+        syncopationSimilarity: number | null;
+    };
+    /** The two most and the two least alike fields, by name. */
+    rationale: string;
+};
+/**
+ * Compare two profiled pieces aspect by aspect: form, harmony, melody and
+ * melodic rhythm.
+ *
+ * Sequences — sections, phrase lengths, cadences, key plans, structural
+ * chords, phrase contours and registers — are aligned by a graded edit
+ * distance; distributions — harmonic function, onset placement, inter-onset
+ * intervals, motif derivations — by histogram intersection. The surface field
+ * compares the motifs' interval cells, so a transposition of the same piece
+ * reads 1 on every field. No aggregate is returned: which aspects agree is the
+ * answer.
+ *
+ * @param a The first profile.
+ * @param b The second profile.
+ * @param opts The work budget.
+ * @returns One likeness per aspect, and a rationale naming the extremes.
+ * @throws {InvalidInputError} If either profile or the options cannot be read.
+ * @throws {BudgetExceededError} If the progression alignment would exceed the budget.
+ * @category Arrangement & Analysis
+ */
+declare function compareReferences(a: ReferenceProfile, b: ReferenceProfile, opts?: ReferenceComparisonOptions): ReferenceComparison;
+
+/**
+ * Boundary validation for {@link ReferenceProfile}: a caller can hand this a
+ * value restored from JSON, a config file, or a plugin host, and every field
+ * is checked before anything downstream reads it. A violation names the path
+ * to the offending field, so a malformed document is diagnosed at the field
+ * that is wrong rather than wherever the first bad read happens to land.
+ */
+
+/**
+ * Reject a value that is not a {@link ReferenceProfile}.
+ *
+ * A profile is the shape a caller's stored JSON, a config file, or a plugin
+ * host most plausibly hands back malformed: a missing field, a distribution
+ * that no longer sums to 1, an index a later edit left dangling, a numeral no
+ * reader can parse. Every field is checked before {@link compareReferences} or
+ * a caller's own code reads it, and a violation names the path to the field
+ * that is wrong.
+ *
+ * @param value The value to check.
+ * @param name What the value is, for the error message.
+ * @returns The same profile.
+ * @throws {InvalidInputError} If the value is not a valid reference profile.
+ * @example
+ * ```ts
+ * import { assertReferenceProfile } from '@libraz/libcantus';
+ * const emptyRhythm = {
+ *   startBeat: 0, endBeat: 0, bars: 0, onsets: 0, onsetDensity: 0,
+ *   barOnsets: [], onsetLevels: [0, 0, 0, 0, 0, 0], barPositions: [],
+ *   interOnsetShares: new Array(17).fill(0), restRatio: 0, syncopation: 0,
+ *   offGridRatio: 0, rationale: 'nothing sounds',
+ * };
+ * const profile = {
+ *   profileVersion: 1,
+ *   span: { startBeat: 0, endBeat: 0, bars: 0 },
+ *   meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
+ *   form: { hypermeter: { groupBars: 1, confidence: 0 }, sections: [], phrases: [] },
+ *   harmony: { keys: [], chords: [], rhythm: emptyRhythm },
+ *   melody: { register: null, shape: null, motifs: [], graph: { nodes: [], edges: [] }, rhythm: emptyRhythm },
+ * };
+ * assertReferenceProfile(profile); // the profile, unchanged
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function assertReferenceProfile(value: unknown, name?: string): ReferenceProfile;
+
 /**
  * Line spelling: name every note of a melodic line in one pass.
  *
@@ -144,8 +290,9 @@ type SpellLineOptions = {
  * 1. A note the sounding chord names takes that chord's spelling of it, even
  *    when the key spells the pitch otherwise — the seventh of a Db7 reads Cb in
  *    C major, not B.
- * 2. Anything else the key's scale spells keeps its key spelling, exactly as
- *    the note-by-note path keeps it.
+ * 2. Anything else the key spells as its own — a scale tone, or the raised
+ *    sixth and seventh of a minor key — keeps its key spelling, so the leading
+ *    tone of A minor reads G# even where the line falls through it.
  * 3. A chromatic note is spelled so the written intervals around it match the
  *    sounding ones, and then so a rising step carries a sharp and a falling
  *    step a flat.
@@ -190,4 +337,5 @@ type SpellLineOptions = {
  */
 declare function spellLine(notes: readonly NoteEvent[], timeline: ChordTimeline | null, key: SpelledKeyLike, opts?: SpellLineOptions): Note[];
 
-export { ChordTimeline, type MelodicComparison, MelodicPhrase, Note as NoteData, NoteEvent, NoteLike, type SpellLineOptions, SpelledKeyLike, compareMelodies, melodicSimilarity, spellLine };
+export { ChordTimeline, MelodicPhrase, Note as NoteData, NoteEvent, NoteLike, ReferenceProfile, SpelledKeyLike, assertReferenceProfile, compareMelodies, compareReferences, melodicSimilarity, spellLine };
+export type { MelodicComparison, ReferenceComparison, ReferenceComparisonOptions, SpellLineOptions };