@libraz/libcantus 1.3.0 → 1.4.0

package/dist/{index-CY-3NVfy.d.cts → index-DVInzCDS.d.cts}

@@ -1,9 +1,9 @@
-import { T as TimeSignature, b as MeterLike, c as MeterMap } from './index-BMweUlm5.cjs';
-import { a as Articulation, h as NoteEvent } from './index-Cy15oTvh.cjs';
-import { S as SeedPath, d as PositionalRng, I as InstrumentProfile, f as StringedProfile } from './positional-DMZer-FM.cjs';
-import { d as ChordQuality, e as ChordSegment, c as ChordLike, K as KeyLike, b as Chord, m as ProfileWeights, g as ChordSpan, n as ResolvedKey, r as SpelledKeyLike } from './coerce-DRERzdve.cjs';
-import { h as ChordTimeline, e as CadenceType, v as MelodicContourShape, P as MotifRelationSummary, a5 as ReferenceProfile, b as BorrowedSource, o as HarmonicFunction } from './types-D-XgxGvp.cjs';
-import { H as HarmonyRole } from './index-BL5N2Oyz.cjs';
+import { T as TimeSignature, b as MeterLike, c as MeterMap } from './index-5VJgKz_Q.cjs';
+import { a as Articulation, h as NoteEvent } from './index-C9MYbuKS.cjs';
+import { S as SeedPath, d as PositionalRng, I as InstrumentProfile, f as StringedProfile } from './positional-CscpxtlE.cjs';
+import { d as ChordQuality, e as ChordSegment, c as ChordLike, K as KeyLike, b as Chord, m as ProfileWeights, g as ChordSpan, n as ResolvedKey, r as SpelledKeyLike } from './coerce-Ytt2Eiq9.cjs';
+import { h as ChordTimeline, e as CadenceType, v as MelodicContourShape, P as MotifRelationSummary, a5 as ReferenceProfile, b as BorrowedSource, o as HarmonicFunction } from './types-_ofpb2be.cjs';
+import { H as HarmonyRole } from './index-BkT21EMv.cjs';
 
 /**
  * The samplers a generator needs, each addressed by the position it is drawing
@@ -547,8 +547,9 @@ declare function thin<T extends GridEvent>(events: readonly T[], amount: number,
  * Fill in the gaps of a figure, one note per gap.
  *
  * Doubling is what a player does when asked for more of the same rather than
- * for something different: the added note sits halfway between two the figure
- * already has, takes its predecessor's identity, and is played softer.
+ * for something different: the added note sits halfway between two onsets of
+ * one stream (the limb, else the voice), takes its predecessor's identity, and
+ * is played softer. A gap between two limbs is no gap for either of them.
  *
  * @param events The figure, which need not be sorted.
  * @param spanSteps Length of the figure in sixteenths.
@@ -574,6 +575,9 @@ declare function halfTime<T extends GridEvent>(events: readonly T[], spanSteps?:
  * The repeat is what makes this the mirror of {@link halfTime} rather than a
  * figure with a hole in it: the bar stays full.
  *
+ * A whole step halves onto the nearest sixteenth; an onset off the straight
+ * grid, a triplet, halves exactly and stays on its own grid.
+ *
  * Halving brings positions together, and two onsets of one stream landing on
  * the same step are one stroke played louder rather than two: a drum struck
  * twice at the same instant is a pair of note-ons a reader turns into a hung or
@@ -713,8 +717,8 @@ type DeformOptions = {
  * const busier = deform(figure, { rhythmic: 0.9 }, draw, 'bar', 0);
  * // Above the neutral middle the figure is syncopated: onsets are added off
  * // the beat, and the result comes back sorted by position.
- * busier.length; // 7
- * busier.map((event) => event.step); // [0, 3, 4, 7, 8, 11, 12]
+ * busier.length; // 6
+ * busier.map((event) => event.step); // [0, 3, 4, 8, 11, 12]
  * ```
  *
  * @category Composition
@@ -747,9 +751,12 @@ declare function withinCeiling(events: readonly GridEvent[], bpm: number | undef
  * Given a sequence of chord segments and a key, this builds a monophonic bass
  * line in a chosen low register. Several idiomatic styles are supported, from a
  * single held root per segment to a quarter-note walking line that leads by
- * step into each chord change. All pitches are kept in a narrow bass band and
- * consecutive notes move by small intervals; given a seed the output is fully
- * reproducible.
+ * step into each chord change. Root-position chord tones are kept in an
+ * octave-wide bass band `[low, low + 12]`. A slash chord's other tones sit up to
+ * an octave above its placed bass, so they can rise past the top of the band,
+ * and the `pop` octave pickup and the walking approach notes leave the band by
+ * design; consecutive notes can therefore lie more than an octave apart. Given
+ * a seed the output is fully reproducible.
  *
  * Positions and durations are measured in quarter-note beats, matching the
  * library-wide convention.
@@ -847,9 +854,12 @@ type BassLineOptions = {
  * Generate a bass line following a chord placement.
  *
  * Each segment contributes notes in the chosen bass register per the selected
- * style; consecutive notes are kept within roughly a fifth. Every note's
- * duration extends to the next onset (the final note extends to the last
- * segment's end). Given a seed the output is fully reproducible.
+ * style. Root-position chord tones lie in the `[low, low + 12]` band; a slash
+ * chord's other tones sit up to an octave above its placed bass, and the `pop`
+ * octave pickup and the walking approach notes leave the band, so consecutive
+ * notes can be more than an octave apart. Every note's duration extends to the
+ * next onset (the final note extends to the last segment's end). Given a seed
+ * the output is fully reproducible.
  *
  * The `pop` style's pickups are drawn per position, so raising
  * `complexity.rhythmic` adds pickups without moving the notes already written.
@@ -1247,6 +1257,8 @@ declare function generateDrums(opts: DrumsOptions): DrumHit[];
 type HumanizeOptions = {
     /**
      * Time signature used to derive metric accents, in any form that names one.
+     * A meter map is read bar by bar, so a note after a change is accented in the
+     * signature in force where it sounds.
      *
      * @defaultValue 4/4
      */
@@ -1374,11 +1386,13 @@ type GrooveTemplate = {
  * template so {@link applyGrooveTemplate} can verify the meter matches.
  *
  * @param events The (typically "groovy", human-played) events to analyze.
- * @param ts The time signature, used to compute the bar length.
+ * @param ts The time signature, used to compute the bar length. A meter map
+ *   is accepted while it keeps one signature throughout.
  * @param subdivision Grid resolution: equal grid steps per quarter-note beat.
  *   Defaults to a sixteenth-note grid, which is where the timing deviations a
  *   template records — swing, push, drag — are audible.
  * @returns The extracted groove template.
+ * @throws If `ts` changes signature.
  * @category Rhythm & Meter
  */
 declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: MeterLike, subdivision?: number): GrooveTemplate;
@@ -1403,11 +1417,13 @@ declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: MeterLi
  *
  * @param events The events to reshape.
  * @param template The groove template, from {@link extractGrooveTemplate}.
- * @param ts The time signature, used to compute the bar length.
+ * @param ts The time signature, used to compute the bar length. A meter map
+ *   is accepted while it keeps one signature throughout.
  * @returns Reshaped copies of `events`, in input order.
- * @throws If `template.ts` is set and does not match `ts`, if `slotsPerBar` is
- *   not the number of slots a bar of `ts` holds at the template's subdivision,
- *   or if a slot carries a non-finite offset or a velocity outside [0, 127].
+ * @throws If `ts` changes signature, if `template.ts` is set and does not
+ *   match `ts`, if `slotsPerBar` is not the number of slots a bar of `ts` holds
+ *   at the template's subdivision, or if a slot carries a non-finite offset or
+ *   a velocity outside [0, 127].
  * @example
  * ```ts
  * import { extractGrooveTemplate, applyGrooveTemplate, parseTimeSignature } from '@libraz/libcantus';
@@ -1603,7 +1619,10 @@ declare function pickProgressionPreset(style: ProgStyle, ctx?: GenerationContext
  * the secondary dominant (V7) of the following chord, flagged with
  * `secondaryDominant`. Only a chord the key can make a local tonic is given one:
  * nothing tonicizes a diminished triad, so the supertonic of a minor key takes
- * no dominant of its own.
+ * no dominant of its own, and a dominant seventh the key already contains
+ * (the tonic seventh of mixolydian) is a native chord rather than an applied
+ * one, so it is not inserted. A chord that already sounds a dominant seventh
+ * onto the next one is left as written.
  *
  * @param opts Generation options.
  * @returns One chord per bar in timeline order.
@@ -1674,7 +1693,7 @@ type HarmonizePlacement = {
  * @category Reharmonization
  */
 type HarmonizeOptions = {
-    /** The melody to harmonize, in ascending onset order. */
+    /** The melody to harmonize, in any order; it is read in onset order. */
     melody: readonly MelodyNote[];
     /**
      * The key to harmonize in, or `'infer'` to estimate it from the melody's
@@ -1974,7 +1993,8 @@ type PlannedRhythm = {
  * The plan is a hard constraint where the generator is free: every root, every
  * span no motif covers and every closing note keeps its phrase's register and
  * offers only the pitches its position class admits — a chord tone on a strong
- * pulse, a scale tone on a weak one, anything in the register off the pulses.
+ * pulse, a scale tone on a weak one or on a strong one where no chord is
+ * planned, anything in the register off the pulses.
  * A derived statement is its source replayed through the named relation at the
  * pitch level that suits its phrase best; there the transformation outranks
  * the harmony, and the register outranks both. A root takes its plan's onset
@@ -2318,7 +2338,8 @@ type OrnamentOptions = {
     amount?: number;
     /**
      * Time signature, in any form that names one, used to tell strong positions
-     * from weak ones.
+     * from weak ones. A meter map is read bar by bar, so a note after a change
+     * is weighed in the signature in force where it sounds.
      *
      * @defaultValue 4/4
      */
@@ -2663,8 +2684,9 @@ type SubstituteOptions = {
  * tritone substitute of G7 formats as `Db7` and its chromatic mediants as `Bb`
  * and `Eb`. Where the substitution's function and the bare pitch class disagree,
  * the function decides — a tritone substitute is a bII7 and so is written on the
- * flattened supertonic of the chord it resolves to, and a borrowed chord takes
- * the spelling of the mode it is borrowed from.
+ * flattened supertonic of the chord it resolves to, a borrowed chord takes the
+ * spelling of the mode it is borrowed from, and a chromatic mediant is written
+ * on the letter a third from the source root (E's mediants are G#, not Ab).
  *
  * @param chord The chord to reharmonize, as a chord symbol or as chord data.
  * @param key The prevailing key, as a key name or as a key/scale.
@@ -2781,7 +2803,8 @@ type RhythmEvent = {
  * @param pitch The MIDI pitch to give every note.
  * @param velocity Velocity for every note; defaults to a mezzo-forte 96.
  * @returns The note events, in the order given.
- * @throws If the pitch or the velocity is not a whole MIDI value in [0, 127].
+ * @throws If the pitch or the velocity is not a whole MIDI value in [0, 127], or an event is not
+ *   a record with a finite position and duration.
  * @example
  * ```ts
  * import { generateRhythm, humanize, rhythmToNoteEvents } from '@libraz/libcantus';
@@ -2867,4 +2890,5 @@ declare function generateRhythm(ts: MeterLike, opts?: RhythmOptions): RhythmEven
  */
 declare function rhythmDensity(events: RhythmEvent[], ts: MeterLike): number;
 
-export { type PlannedSection as $, type GrooveSlot as A, BAR_STEPS as B, COMPOSITION_PLAN_VERSION as C, DRUM_NOTES as D, type EuclideanKick as E, type GrooveStyle as F, GENRES as G, type GrooveTemplate as H, type HarmonizeOptions as I, type HarmonizePlacement as J, type HarmonizeResult as K, type HumanizeOptions as L, type MelodyNote as M, type MelodyOptions as N, type MotifCell as O, type MotifContour as P, type MotifNote as Q, type MotifOptions as R, type MotifTransform as S, ORNAMENT_STYLES as T, type OrnamentOptions as U, type OrnamentStyle as V, PROVENANCE_BASES as W, type PlannedChord as X, type PlannedMotif as Y, type PlannedPhrase as Z, type PlannedRhythm as _, BASS_STYLES as a, type PreserveWeights as a0, type ProgFunction as a1, type ProgStyle as a2, type ProgressionDegree as a3, type ProgressionOptions as a4, type ProgressionPreset as a5, type Provenance as a6, type ProvenanceBasis as a7, type ResolvedContext as a8, type RhythmEvent as a9, generateRhythm as aA, gridMetricWeight as aB, halfTime as aC, humanize as aD, mergeVocabulary as aE, modalInterchangePalette as aF, motifToNoteEvents as aG, negativeHarmonyMirror as aH, onsetWeightCurve as aI, ornament as aJ, ornamentBy as aK, pickProgressionPreset as aL, pickVocabulary as aM, progressions as aN, progressionsByStyle as aO, resolveContext as aP, rhythmDensity as aQ, rhythmToNoteEvents as aR, selectVocabulary as aS, substituteChord as aT, syncopate as aU, thin as aV, transformMotif as aW, vocabularyOfKind as aX, withinCeiling as aY, type RhythmOptions as aa, STEP_BEATS as ab, type Section as ac, type SubstituteOptions as ad, type Substitution as ae, type SubstitutionType as af, type SyncopateOptions as ag, type Vocabulary as ah, type VocabularyQuery as ai, applyGrooveTemplate as aj, assertVocabulary as ak, deform as al, deriveCompositionPlan as am, developMotif as an, double as ao, doubleTime as ap, drumVoiceOf as aq, evaluateComposition as ar, extractGrooveTemplate as as, fitsQuery as at, generateBassLine as au, generateCounterMelody as av, generateDrums as aw, generateMelody as ax, generateMotif as ay, generateProgression as az, BEAT_STEPS as b, BORROWED_DEGREES as c, type BassLineOptions as d, type BassSegment as e, type BassStyle as f, type BorrowedChord as g, type Complexity as h, type CompositionEvaluation as i, type CompositionPlan as j, type CompositionPlanOptions as k, type CompositionViolation as l, type CounterMelodyOptions as m, type DeformOptions as n, type Draw as o, type DrumHit as p, type DrumRole as q, type DrumStyle as r, type DrumVoice as s, type DrumsOptions as t, type EvaluateCompositionOptions as u, type GenerationContext as v, type GenerationContextInput as w, type Genre as x, type GridEvent as y, type GrooveFeel as z };
+export { BAR_STEPS as B, COMPOSITION_PLAN_VERSION as C, DRUM_NOTES as D, GENRES as G, ORNAMENT_STYLES as T, PROVENANCE_BASES as W, BASS_STYLES as a, generateRhythm as aA, gridMetricWeight as aB, halfTime as aC, humanize as aD, mergeVocabulary as aE, modalInterchangePalette as aF, motifToNoteEvents as aG, negativeHarmonyMirror as aH, onsetWeightCurve as aI, ornament as aJ, ornamentBy as aK, pickProgressionPreset as aL, pickVocabulary as aM, progressions as aN, progressionsByStyle as aO, resolveContext as aP, rhythmDensity as aQ, rhythmToNoteEvents as aR, selectVocabulary as aS, substituteChord as aT, syncopate as aU, thin as aV, transformMotif as aW, vocabularyOfKind as aX, withinCeiling as aY, STEP_BEATS as ab, applyGrooveTemplate as aj, assertVocabulary as ak, deform as al, deriveCompositionPlan as am, developMotif as an, double as ao, doubleTime as ap, drumVoiceOf as aq, evaluateComposition as ar, extractGrooveTemplate as as, fitsQuery as at, generateBassLine as au, generateCounterMelody as av, generateDrums as aw, generateMelody as ax, generateMotif as ay, generateProgression as az, BEAT_STEPS as b, BORROWED_DEGREES as c };
+export type { PlannedSection as $, GrooveSlot as A, EuclideanKick as E, GrooveStyle as F, GrooveTemplate as H, HarmonizeOptions as I, HarmonizePlacement as J, HarmonizeResult as K, HumanizeOptions as L, MelodyNote as M, MelodyOptions as N, MotifCell as O, MotifContour as P, MotifNote as Q, MotifOptions as R, MotifTransform as S, OrnamentOptions as U, OrnamentStyle as V, PlannedChord as X, PlannedMotif as Y, PlannedPhrase as Z, PlannedRhythm as _, PreserveWeights as a0, ProgFunction as a1, ProgStyle as a2, ProgressionDegree as a3, ProgressionOptions as a4, ProgressionPreset as a5, Provenance as a6, ProvenanceBasis as a7, ResolvedContext as a8, RhythmEvent as a9, RhythmOptions as aa, Section as ac, SubstituteOptions as ad, Substitution as ae, SubstitutionType as af, SyncopateOptions as ag, Vocabulary as ah, VocabularyQuery as ai, BassLineOptions as d, BassSegment as e, BassStyle as f, BorrowedChord as g, Complexity as h, CompositionEvaluation as i, CompositionPlan as j, CompositionPlanOptions as k, CompositionViolation as l, CounterMelodyOptions as m, DeformOptions as n, Draw as o, DrumHit as p, DrumRole as q, DrumStyle as r, DrumVoice as s, DrumsOptions as t, EvaluateCompositionOptions as u, GenerationContext as v, GenerationContextInput as w, Genre as x, GridEvent as y, GrooveFeel as z };

package/dist/{index-9eoQs2C1.d.ts → index-Dg-SAfhz.d.ts}

@@ -1,5 +1,5 @@
-import { h as NoteEvent } from './index-Cy15oTvh.js';
-import { e as StringFingering, c as Limb, b as InstrumentProfileLike } from './positional-DJgs6ltD.js';
+import { h as NoteEvent } from './index-C9MYbuKS.js';
+import { e as StringFingering, c as Limb, b as InstrumentProfileLike } from './positional-DLnfUgqG.js';
 
 /**
  * What makes a passage hard or impossible on an instrument.
@@ -453,7 +453,8 @@ declare function tempoAt(beat: number, map: TempoMap): number;
  * @param beat Position or length in quarter-note beats.
  * @param ppq Pulses (ticks) per quarter note, e.g. 96, 480, or 960.
  * @returns The whole tick count.
- * @throws If `beat` is not finite or `ppq` is not a positive integer.
+ * @throws If `beat` is not finite, `ppq` is not a positive integer, or the
+ *   tick count is past the safe integers.
  * @example
  * ```ts
  * import { beatsToTicks } from '@libraz/libcantus';
@@ -655,4 +656,5 @@ declare const JUST_RATIOS: Readonly<Record<0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
  */
 declare function justDeviationCents(semitoneClass: number): number;
 
-export { playability as A, ratioToCents as B, secondsToBeats as C, type DurationData as D, stepOf as E, stepsOfCents as F, tempoAt as G, ticksToBeats as H, type IndexedNoteEvent as I, JUST_RATIOS as J, NOTE_VALUES as N, type OnsetTieBreak as O, type PlayabilityIssue as P, type SpelledDuration as S, TWELVE_TET as T, type NoteEventIndex as a, type NoteEventIndexOptions as b, type NotePlacement as c, type NoteValue as d, type PlayabilityIssueType as e, type PlayabilityLayer as f, type PlayabilityReport as g, type TempoEvent as h, type TempoMap as i, type TuningTable as j, type Tuplet as k, beatsToDuration as l, beatsToSeconds as m, beatsToTicks as n, beatsToTiedDurations as o, centsBetweenFreq as p, centsFromNearestStep as q, centsOfSteps as r, centsToRatio as s, createNoteEventIndex as t, durationToBeats as u, durationToSeconds as v, edo as w, frequencyOf as x, justDeviationCents as y, nearestStep as z };
+export { playability as A, ratioToCents as B, secondsToBeats as C, stepOf as E, stepsOfCents as F, tempoAt as G, ticksToBeats as H, JUST_RATIOS as J, NOTE_VALUES as N, TWELVE_TET as T, beatsToDuration as l, beatsToSeconds as m, beatsToTicks as n, beatsToTiedDurations as o, centsBetweenFreq as p, centsFromNearestStep as q, centsOfSteps as r, centsToRatio as s, createNoteEventIndex as t, durationToBeats as u, durationToSeconds as v, edo as w, frequencyOf as x, justDeviationCents as y, nearestStep as z };
+export type { DurationData as D, IndexedNoteEvent as I, OnsetTieBreak as O, PlayabilityIssue as P, SpelledDuration as S, NoteEventIndex as a, NoteEventIndexOptions as b, NotePlacement as c, NoteValue as d, PlayabilityIssueType as e, PlayabilityLayer as f, PlayabilityReport as g, TempoEvent as h, TempoMap as i, TuningTable as j, Tuplet as k };

package/dist/{index-zaZdmnU4.d.ts → index-jgeug9EA.d.ts}

@@ -1,9 +1,9 @@
-import { T as TimeSignature, b as MeterLike, c as MeterMap } from './index-CL4b4gUQ.js';
-import { a as Articulation, h as NoteEvent } from './index-Cy15oTvh.js';
-import { S as SeedPath, d as PositionalRng, I as InstrumentProfile, f as StringedProfile } from './positional-DJgs6ltD.js';
-import { d as ChordQuality, e as ChordSegment, c as ChordLike, K as KeyLike, b as Chord, m as ProfileWeights, g as ChordSpan, n as ResolvedKey, r as SpelledKeyLike } from './coerce-DP0vYu-x.js';
-import { h as ChordTimeline, e as CadenceType, v as MelodicContourShape, P as MotifRelationSummary, a5 as ReferenceProfile, b as BorrowedSource, o as HarmonicFunction } from './types-Dh7C064C.js';
-import { H as HarmonyRole } from './index-Dw2DP7vm.js';
+import { T as TimeSignature, b as MeterLike, c as MeterMap } from './index-Bf0Sv8a9.js';
+import { a as Articulation, h as NoteEvent } from './index-C9MYbuKS.js';
+import { S as SeedPath, d as PositionalRng, I as InstrumentProfile, f as StringedProfile } from './positional-DLnfUgqG.js';
+import { d as ChordQuality, e as ChordSegment, c as ChordLike, K as KeyLike, b as Chord, m as ProfileWeights, g as ChordSpan, n as ResolvedKey, r as SpelledKeyLike } from './coerce-CUhHc3Tu.js';
+import { h as ChordTimeline, e as CadenceType, v as MelodicContourShape, P as MotifRelationSummary, a5 as ReferenceProfile, b as BorrowedSource, o as HarmonicFunction } from './types-7mGFwvMm.js';
+import { H as HarmonyRole } from './index-C7KCaTRz.js';
 
 /**
  * The samplers a generator needs, each addressed by the position it is drawing
@@ -547,8 +547,9 @@ declare function thin<T extends GridEvent>(events: readonly T[], amount: number,
  * Fill in the gaps of a figure, one note per gap.
  *
  * Doubling is what a player does when asked for more of the same rather than
- * for something different: the added note sits halfway between two the figure
- * already has, takes its predecessor's identity, and is played softer.
+ * for something different: the added note sits halfway between two onsets of
+ * one stream (the limb, else the voice), takes its predecessor's identity, and
+ * is played softer. A gap between two limbs is no gap for either of them.
  *
  * @param events The figure, which need not be sorted.
  * @param spanSteps Length of the figure in sixteenths.
@@ -574,6 +575,9 @@ declare function halfTime<T extends GridEvent>(events: readonly T[], spanSteps?:
  * The repeat is what makes this the mirror of {@link halfTime} rather than a
  * figure with a hole in it: the bar stays full.
  *
+ * A whole step halves onto the nearest sixteenth; an onset off the straight
+ * grid, a triplet, halves exactly and stays on its own grid.
+ *
  * Halving brings positions together, and two onsets of one stream landing on
  * the same step are one stroke played louder rather than two: a drum struck
  * twice at the same instant is a pair of note-ons a reader turns into a hung or
@@ -713,8 +717,8 @@ type DeformOptions = {
  * const busier = deform(figure, { rhythmic: 0.9 }, draw, 'bar', 0);
  * // Above the neutral middle the figure is syncopated: onsets are added off
  * // the beat, and the result comes back sorted by position.
- * busier.length; // 7
- * busier.map((event) => event.step); // [0, 3, 4, 7, 8, 11, 12]
+ * busier.length; // 6
+ * busier.map((event) => event.step); // [0, 3, 4, 8, 11, 12]
  * ```
  *
  * @category Composition
@@ -747,9 +751,12 @@ declare function withinCeiling(events: readonly GridEvent[], bpm: number | undef
  * Given a sequence of chord segments and a key, this builds a monophonic bass
  * line in a chosen low register. Several idiomatic styles are supported, from a
  * single held root per segment to a quarter-note walking line that leads by
- * step into each chord change. All pitches are kept in a narrow bass band and
- * consecutive notes move by small intervals; given a seed the output is fully
- * reproducible.
+ * step into each chord change. Root-position chord tones are kept in an
+ * octave-wide bass band `[low, low + 12]`. A slash chord's other tones sit up to
+ * an octave above its placed bass, so they can rise past the top of the band,
+ * and the `pop` octave pickup and the walking approach notes leave the band by
+ * design; consecutive notes can therefore lie more than an octave apart. Given
+ * a seed the output is fully reproducible.
  *
  * Positions and durations are measured in quarter-note beats, matching the
  * library-wide convention.
@@ -847,9 +854,12 @@ type BassLineOptions = {
  * Generate a bass line following a chord placement.
  *
  * Each segment contributes notes in the chosen bass register per the selected
- * style; consecutive notes are kept within roughly a fifth. Every note's
- * duration extends to the next onset (the final note extends to the last
- * segment's end). Given a seed the output is fully reproducible.
+ * style. Root-position chord tones lie in the `[low, low + 12]` band; a slash
+ * chord's other tones sit up to an octave above its placed bass, and the `pop`
+ * octave pickup and the walking approach notes leave the band, so consecutive
+ * notes can be more than an octave apart. Every note's duration extends to the
+ * next onset (the final note extends to the last segment's end). Given a seed
+ * the output is fully reproducible.
  *
  * The `pop` style's pickups are drawn per position, so raising
  * `complexity.rhythmic` adds pickups without moving the notes already written.
@@ -1247,6 +1257,8 @@ declare function generateDrums(opts: DrumsOptions): DrumHit[];
 type HumanizeOptions = {
     /**
      * Time signature used to derive metric accents, in any form that names one.
+     * A meter map is read bar by bar, so a note after a change is accented in the
+     * signature in force where it sounds.
      *
      * @defaultValue 4/4
      */
@@ -1374,11 +1386,13 @@ type GrooveTemplate = {
  * template so {@link applyGrooveTemplate} can verify the meter matches.
  *
  * @param events The (typically "groovy", human-played) events to analyze.
- * @param ts The time signature, used to compute the bar length.
+ * @param ts The time signature, used to compute the bar length. A meter map
+ *   is accepted while it keeps one signature throughout.
  * @param subdivision Grid resolution: equal grid steps per quarter-note beat.
  *   Defaults to a sixteenth-note grid, which is where the timing deviations a
  *   template records — swing, push, drag — are audible.
  * @returns The extracted groove template.
+ * @throws If `ts` changes signature.
  * @category Rhythm & Meter
  */
 declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: MeterLike, subdivision?: number): GrooveTemplate;
@@ -1403,11 +1417,13 @@ declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: MeterLi
  *
  * @param events The events to reshape.
  * @param template The groove template, from {@link extractGrooveTemplate}.
- * @param ts The time signature, used to compute the bar length.
+ * @param ts The time signature, used to compute the bar length. A meter map
+ *   is accepted while it keeps one signature throughout.
  * @returns Reshaped copies of `events`, in input order.
- * @throws If `template.ts` is set and does not match `ts`, if `slotsPerBar` is
- *   not the number of slots a bar of `ts` holds at the template's subdivision,
- *   or if a slot carries a non-finite offset or a velocity outside [0, 127].
+ * @throws If `ts` changes signature, if `template.ts` is set and does not
+ *   match `ts`, if `slotsPerBar` is not the number of slots a bar of `ts` holds
+ *   at the template's subdivision, or if a slot carries a non-finite offset or
+ *   a velocity outside [0, 127].
  * @example
  * ```ts
  * import { extractGrooveTemplate, applyGrooveTemplate, parseTimeSignature } from '@libraz/libcantus';
@@ -1603,7 +1619,10 @@ declare function pickProgressionPreset(style: ProgStyle, ctx?: GenerationContext
  * the secondary dominant (V7) of the following chord, flagged with
  * `secondaryDominant`. Only a chord the key can make a local tonic is given one:
  * nothing tonicizes a diminished triad, so the supertonic of a minor key takes
- * no dominant of its own.
+ * no dominant of its own, and a dominant seventh the key already contains
+ * (the tonic seventh of mixolydian) is a native chord rather than an applied
+ * one, so it is not inserted. A chord that already sounds a dominant seventh
+ * onto the next one is left as written.
  *
  * @param opts Generation options.
  * @returns One chord per bar in timeline order.
@@ -1674,7 +1693,7 @@ type HarmonizePlacement = {
  * @category Reharmonization
  */
 type HarmonizeOptions = {
-    /** The melody to harmonize, in ascending onset order. */
+    /** The melody to harmonize, in any order; it is read in onset order. */
     melody: readonly MelodyNote[];
     /**
      * The key to harmonize in, or `'infer'` to estimate it from the melody's
@@ -1974,7 +1993,8 @@ type PlannedRhythm = {
  * The plan is a hard constraint where the generator is free: every root, every
  * span no motif covers and every closing note keeps its phrase's register and
  * offers only the pitches its position class admits — a chord tone on a strong
- * pulse, a scale tone on a weak one, anything in the register off the pulses.
+ * pulse, a scale tone on a weak one or on a strong one where no chord is
+ * planned, anything in the register off the pulses.
  * A derived statement is its source replayed through the named relation at the
  * pitch level that suits its phrase best; there the transformation outranks
  * the harmony, and the register outranks both. A root takes its plan's onset
@@ -2318,7 +2338,8 @@ type OrnamentOptions = {
     amount?: number;
     /**
      * Time signature, in any form that names one, used to tell strong positions
-     * from weak ones.
+     * from weak ones. A meter map is read bar by bar, so a note after a change
+     * is weighed in the signature in force where it sounds.
      *
      * @defaultValue 4/4
      */
@@ -2663,8 +2684,9 @@ type SubstituteOptions = {
  * tritone substitute of G7 formats as `Db7` and its chromatic mediants as `Bb`
  * and `Eb`. Where the substitution's function and the bare pitch class disagree,
  * the function decides — a tritone substitute is a bII7 and so is written on the
- * flattened supertonic of the chord it resolves to, and a borrowed chord takes
- * the spelling of the mode it is borrowed from.
+ * flattened supertonic of the chord it resolves to, a borrowed chord takes the
+ * spelling of the mode it is borrowed from, and a chromatic mediant is written
+ * on the letter a third from the source root (E's mediants are G#, not Ab).
  *
  * @param chord The chord to reharmonize, as a chord symbol or as chord data.
  * @param key The prevailing key, as a key name or as a key/scale.
@@ -2781,7 +2803,8 @@ type RhythmEvent = {
  * @param pitch The MIDI pitch to give every note.
  * @param velocity Velocity for every note; defaults to a mezzo-forte 96.
  * @returns The note events, in the order given.
- * @throws If the pitch or the velocity is not a whole MIDI value in [0, 127].
+ * @throws If the pitch or the velocity is not a whole MIDI value in [0, 127], or an event is not
+ *   a record with a finite position and duration.
  * @example
  * ```ts
  * import { generateRhythm, humanize, rhythmToNoteEvents } from '@libraz/libcantus';
@@ -2867,4 +2890,5 @@ declare function generateRhythm(ts: MeterLike, opts?: RhythmOptions): RhythmEven
  */
 declare function rhythmDensity(events: RhythmEvent[], ts: MeterLike): number;
 
-export { type PlannedSection as $, type GrooveSlot as A, BAR_STEPS as B, COMPOSITION_PLAN_VERSION as C, DRUM_NOTES as D, type EuclideanKick as E, type GrooveStyle as F, GENRES as G, type GrooveTemplate as H, type HarmonizeOptions as I, type HarmonizePlacement as J, type HarmonizeResult as K, type HumanizeOptions as L, type MelodyNote as M, type MelodyOptions as N, type MotifCell as O, type MotifContour as P, type MotifNote as Q, type MotifOptions as R, type MotifTransform as S, ORNAMENT_STYLES as T, type OrnamentOptions as U, type OrnamentStyle as V, PROVENANCE_BASES as W, type PlannedChord as X, type PlannedMotif as Y, type PlannedPhrase as Z, type PlannedRhythm as _, BASS_STYLES as a, type PreserveWeights as a0, type ProgFunction as a1, type ProgStyle as a2, type ProgressionDegree as a3, type ProgressionOptions as a4, type ProgressionPreset as a5, type Provenance as a6, type ProvenanceBasis as a7, type ResolvedContext as a8, type RhythmEvent as a9, generateRhythm as aA, gridMetricWeight as aB, halfTime as aC, humanize as aD, mergeVocabulary as aE, modalInterchangePalette as aF, motifToNoteEvents as aG, negativeHarmonyMirror as aH, onsetWeightCurve as aI, ornament as aJ, ornamentBy as aK, pickProgressionPreset as aL, pickVocabulary as aM, progressions as aN, progressionsByStyle as aO, resolveContext as aP, rhythmDensity as aQ, rhythmToNoteEvents as aR, selectVocabulary as aS, substituteChord as aT, syncopate as aU, thin as aV, transformMotif as aW, vocabularyOfKind as aX, withinCeiling as aY, type RhythmOptions as aa, STEP_BEATS as ab, type Section as ac, type SubstituteOptions as ad, type Substitution as ae, type SubstitutionType as af, type SyncopateOptions as ag, type Vocabulary as ah, type VocabularyQuery as ai, applyGrooveTemplate as aj, assertVocabulary as ak, deform as al, deriveCompositionPlan as am, developMotif as an, double as ao, doubleTime as ap, drumVoiceOf as aq, evaluateComposition as ar, extractGrooveTemplate as as, fitsQuery as at, generateBassLine as au, generateCounterMelody as av, generateDrums as aw, generateMelody as ax, generateMotif as ay, generateProgression as az, BEAT_STEPS as b, BORROWED_DEGREES as c, type BassLineOptions as d, type BassSegment as e, type BassStyle as f, type BorrowedChord as g, type Complexity as h, type CompositionEvaluation as i, type CompositionPlan as j, type CompositionPlanOptions as k, type CompositionViolation as l, type CounterMelodyOptions as m, type DeformOptions as n, type Draw as o, type DrumHit as p, type DrumRole as q, type DrumStyle as r, type DrumVoice as s, type DrumsOptions as t, type EvaluateCompositionOptions as u, type GenerationContext as v, type GenerationContextInput as w, type Genre as x, type GridEvent as y, type GrooveFeel as z };
+export { BAR_STEPS as B, COMPOSITION_PLAN_VERSION as C, DRUM_NOTES as D, GENRES as G, ORNAMENT_STYLES as T, PROVENANCE_BASES as W, BASS_STYLES as a, generateRhythm as aA, gridMetricWeight as aB, halfTime as aC, humanize as aD, mergeVocabulary as aE, modalInterchangePalette as aF, motifToNoteEvents as aG, negativeHarmonyMirror as aH, onsetWeightCurve as aI, ornament as aJ, ornamentBy as aK, pickProgressionPreset as aL, pickVocabulary as aM, progressions as aN, progressionsByStyle as aO, resolveContext as aP, rhythmDensity as aQ, rhythmToNoteEvents as aR, selectVocabulary as aS, substituteChord as aT, syncopate as aU, thin as aV, transformMotif as aW, vocabularyOfKind as aX, withinCeiling as aY, STEP_BEATS as ab, applyGrooveTemplate as aj, assertVocabulary as ak, deform as al, deriveCompositionPlan as am, developMotif as an, double as ao, doubleTime as ap, drumVoiceOf as aq, evaluateComposition as ar, extractGrooveTemplate as as, fitsQuery as at, generateBassLine as au, generateCounterMelody as av, generateDrums as aw, generateMelody as ax, generateMotif as ay, generateProgression as az, BEAT_STEPS as b, BORROWED_DEGREES as c };
+export type { PlannedSection as $, GrooveSlot as A, EuclideanKick as E, GrooveStyle as F, GrooveTemplate as H, HarmonizeOptions as I, HarmonizePlacement as J, HarmonizeResult as K, HumanizeOptions as L, MelodyNote as M, MelodyOptions as N, MotifCell as O, MotifContour as P, MotifNote as Q, MotifOptions as R, MotifTransform as S, OrnamentOptions as U, OrnamentStyle as V, PlannedChord as X, PlannedMotif as Y, PlannedPhrase as Z, PlannedRhythm as _, PreserveWeights as a0, ProgFunction as a1, ProgStyle as a2, ProgressionDegree as a3, ProgressionOptions as a4, ProgressionPreset as a5, Provenance as a6, ProvenanceBasis as a7, ResolvedContext as a8, RhythmEvent as a9, RhythmOptions as aa, Section as ac, SubstituteOptions as ad, Substitution as ae, SubstitutionType as af, SyncopateOptions as ag, Vocabulary as ah, VocabularyQuery as ai, BassLineOptions as d, BassSegment as e, BassStyle as f, BorrowedChord as g, Complexity as h, CompositionEvaluation as i, CompositionPlan as j, CompositionPlanOptions as k, CompositionViolation as l, CounterMelodyOptions as m, DeformOptions as n, Draw as o, DrumHit as p, DrumRole as q, DrumStyle as r, DrumVoice as s, DrumsOptions as t, EvaluateCompositionOptions as u, GenerationContext as v, GenerationContextInput as w, Genre as x, GridEvent as y, GrooveFeel as z };

package/dist/{index-cHvbYgJI.d.cts → index-pQihL4z7.d.cts}

@@ -1,5 +1,5 @@
-import { h as NoteEvent } from './index-Cy15oTvh.cjs';
-import { e as StringFingering, c as Limb, b as InstrumentProfileLike } from './positional-DMZer-FM.cjs';
+import { h as NoteEvent } from './index-C9MYbuKS.cjs';
+import { e as StringFingering, c as Limb, b as InstrumentProfileLike } from './positional-CscpxtlE.cjs';
 
 /**
  * What makes a passage hard or impossible on an instrument.
@@ -453,7 +453,8 @@ declare function tempoAt(beat: number, map: TempoMap): number;
  * @param beat Position or length in quarter-note beats.
  * @param ppq Pulses (ticks) per quarter note, e.g. 96, 480, or 960.
  * @returns The whole tick count.
- * @throws If `beat` is not finite or `ppq` is not a positive integer.
+ * @throws If `beat` is not finite, `ppq` is not a positive integer, or the
+ *   tick count is past the safe integers.
  * @example
  * ```ts
  * import { beatsToTicks } from '@libraz/libcantus';
@@ -655,4 +656,5 @@ declare const JUST_RATIOS: Readonly<Record<0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
  */
 declare function justDeviationCents(semitoneClass: number): number;
 
-export { playability as A, ratioToCents as B, secondsToBeats as C, type DurationData as D, stepOf as E, stepsOfCents as F, tempoAt as G, ticksToBeats as H, type IndexedNoteEvent as I, JUST_RATIOS as J, NOTE_VALUES as N, type OnsetTieBreak as O, type PlayabilityIssue as P, type SpelledDuration as S, TWELVE_TET as T, type NoteEventIndex as a, type NoteEventIndexOptions as b, type NotePlacement as c, type NoteValue as d, type PlayabilityIssueType as e, type PlayabilityLayer as f, type PlayabilityReport as g, type TempoEvent as h, type TempoMap as i, type TuningTable as j, type Tuplet as k, beatsToDuration as l, beatsToSeconds as m, beatsToTicks as n, beatsToTiedDurations as o, centsBetweenFreq as p, centsFromNearestStep as q, centsOfSteps as r, centsToRatio as s, createNoteEventIndex as t, durationToBeats as u, durationToSeconds as v, edo as w, frequencyOf as x, justDeviationCents as y, nearestStep as z };
+export { playability as A, ratioToCents as B, secondsToBeats as C, stepOf as E, stepsOfCents as F, tempoAt as G, ticksToBeats as H, JUST_RATIOS as J, NOTE_VALUES as N, TWELVE_TET as T, beatsToDuration as l, beatsToSeconds as m, beatsToTicks as n, beatsToTiedDurations as o, centsBetweenFreq as p, centsFromNearestStep as q, centsOfSteps as r, centsToRatio as s, createNoteEventIndex as t, durationToBeats as u, durationToSeconds as v, edo as w, frequencyOf as x, justDeviationCents as y, nearestStep as z };
+export type { DurationData as D, IndexedNoteEvent as I, OnsetTieBreak as O, PlayabilityIssue as P, SpelledDuration as S, NoteEventIndex as a, NoteEventIndexOptions as b, NotePlacement as c, NoteValue as d, PlayabilityIssueType as e, PlayabilityLayer as f, PlayabilityReport as g, TempoEvent as h, TempoMap as i, TuningTable as j, Tuplet as k };