@libraz/libcantus 0.9.5 → 1.0.1

package/dist/model/index.js

@@ -1,20 +1,52 @@
 import {
+  Arrangement,
   Chord,
+  Composer,
+  Duration,
+  Instrument,
   Interval,
   Key,
+  Meter,
+  Motif,
   Note,
-  Progression
-} from "../chunk-3KX76RLG.js";
-import "../chunk-7JEP3MFY.js";
-import "../chunk-NNB67XA2.js";
-import "../chunk-7EONYVI5.js";
-import "../chunk-KBTTEX7Q.js";
-import "../chunk-R2VVFAIN.js";
+  Progression,
+  Rhythm,
+  Score,
+  Tempo,
+  Timeline,
+  Tuning,
+  Voicing
+} from "../chunk-PKFNUHDY.js";
+import "../chunk-2LCPM3EG.js";
+import "../chunk-YH3BIKHH.js";
+import "../chunk-VOHZB45S.js";
+import "../chunk-H42UHPYW.js";
+import "../chunk-FVSI36UV.js";
+import "../chunk-ELCTZUJJ.js";
+import "../chunk-H3VORETI.js";
+import "../chunk-KNJEKLKV.js";
+import {
+  NoteSafety
+} from "../chunk-INHVXP6Z.js";
+import "../chunk-VTI6FOLB.js";
 export {
+  Arrangement,
   Chord,
+  Composer,
+  Duration,
+  Instrument,
   Interval,
   Key,
+  Meter,
+  Motif,
   Note,
-  Progression
+  NoteSafety,
+  Progression,
+  Rhythm,
+  Score,
+  Tempo,
+  Timeline,
+  Tuning,
+  Voicing
 };
 //# sourceMappingURL=index.js.map

package/dist/positional-Cptlj-xs.d.ts

@@ -0,0 +1,287 @@
+import { a as Articulation } from './index-B9MNZboQ.js';
+
+/**
+ * Every limb a percussionist strikes with, in declaration order.
+ *
+ * @category Core
+ */
+declare const LIMBS: readonly ["rightHand", "leftHand", "rightFoot", "leftFoot"];
+/**
+ * One limb of a percussionist.
+ *
+ * @category Core
+ */
+type Limb = (typeof LIMBS)[number];
+/**
+ * Fields every instrument profile carries, whatever its family.
+ *
+ * @category Core
+ */
+type InstrumentProfileCommon = {
+    /** Instrument name, for issue messages and for the caller's own display. */
+    name: string;
+    /** Techniques this instrument can produce; anything else it cannot play. */
+    articulations: readonly Articulation[];
+    /** Greatest number of notes that can sound at once. */
+    polyphony: number;
+};
+/**
+ * A fretted or fretless string instrument, described by what it is rather than
+ * by the range it happens to have.
+ *
+ * The sounding range follows from `tuning` and `frets`: string `s` sounds
+ * `tuning[s] .. tuning[s] + frets`. Storing `[min, max]` instead would make a
+ * five-string bass, a drop tuning, a seven-string guitar and an extended-range
+ * neck four unrelated special cases, and would leave "the neck is not long
+ * enough" indistinguishable from "the note is below the instrument".
+ *
+ * @category Core
+ */
+type StringedProfile = InstrumentProfileCommon & {
+    kind: 'stringed';
+    /** Open-string MIDI pitch per string, lowest-sounding string first. */
+    tuning: readonly number[];
+    /** Highest fret number; fret 0 is the open string. */
+    frets: number;
+    /** Greatest fret span one hand can hold down at once. */
+    maxStretch: number;
+    /**
+     * The neck has no frets. Positions are continuous, so intonation is the
+     * player's and a slide is unbroken; in twelve-tone equal temperament the
+     * positions coincide with fret numbers, so range and stretch are read the
+     * same way.
+     */
+    fretless?: boolean;
+};
+/**
+ * A percussion setup, described by the voices within reach of each limb.
+ *
+ * A kit's constraint is not range but limbs: a voice no limb can reach is not
+ * on the instrument, and two voices needing the same limb at the same instant
+ * cannot both sound.
+ *
+ * @category Core
+ */
+type PercussionProfile = InstrumentProfileCommon & {
+    kind: 'percussion';
+    /** The limbs the player has available. */
+    limbs: readonly Limb[];
+    /** Limbs that can strike each voice, in preference order, keyed by MIDI note. */
+    reach: Readonly<Record<number, readonly Limb[]>>;
+};
+/**
+ * An instrument the library can check a passage against.
+ *
+ * @category Core
+ */
+type InstrumentProfile = StringedProfile | PercussionProfile;
+/**
+ * Anything that names an instrument: a plain {@link InstrumentProfile}, or a
+ * value that serializes to one such as the `Instrument` class.
+ *
+ * Every entry point that takes an instrument takes this, so a caller holding
+ * the class hands it over as it is instead of unwrapping it for one call and
+ * wrapping it again for the next.
+ *
+ * @category Core
+ */
+type InstrumentProfileLike = InstrumentProfile | {
+    /** The profile data this value stands for. */
+    toJSON(): InstrumentProfile;
+};
+/**
+ * A fretting-hand position: which string, and how far up the neck.
+ *
+ * @category Core
+ */
+type StringFingering = {
+    /** Index into the `tuning` of a {@link StringedProfile}. */
+    string: number;
+    /** Fret number; 0 is the open string. */
+    fret: number;
+};
+/**
+ * The lowest and highest pitch an instrument sounds.
+ *
+ * For a string instrument this is derived from the tuning and the fret count,
+ * never stored; for a kit it is the extent of the voices the player's limbs
+ * reach. The range is not necessarily gapless — use {@link canSound} to ask
+ * about one pitch.
+ *
+ * @param profile The instrument.
+ * @returns The extreme sounding pitches, inclusive.
+ *
+ * @example
+ * ```ts
+ * import { BASS_5_STRING, instrumentRange } from '@libraz/libcantus';
+ * instrumentRange(BASS_5_STRING).low; // 23, low B
+ * ```
+ * @category Core
+ */
+declare function instrumentRange(profile: InstrumentProfile): {
+    low: number;
+    high: number;
+};
+/**
+ * Whether the instrument has this pitch at all.
+ *
+ * This is the first of the three playability layers: no amount of skill or
+ * rehearsal puts a note on an instrument that has no position for it.
+ *
+ * @param profile The instrument.
+ * @param pitch MIDI pitch.
+ * @returns True when some string and fret, or some limb the player has,
+ *   produces it.
+ * @category Core
+ */
+declare function canSound(profile: InstrumentProfile, pitch: number): boolean;
+/**
+ * Every position on the neck that sounds a pitch, lowest string first.
+ *
+ * @param profile The instrument.
+ * @param pitch MIDI pitch.
+ * @returns One entry per string that reaches the pitch; empty when none does.
+ * @category Core
+ */
+declare function fingeringsFor(profile: StringedProfile, pitch: number): StringFingering[];
+/**
+ * Move a pitch by whole octaves until the instrument can sound it.
+ *
+ * This is what a player does with a line written below the instrument: the note
+ * comes back an octave up, keeping its pitch class and its place in the phrase.
+ * Substituting a different scale degree, or refusing the passage outright, is
+ * the wrong answer for a bass line.
+ *
+ * @param pitch MIDI pitch to place.
+ * @param profile The instrument.
+ * @returns The nearest octave transposition the instrument sounds, searching
+ *   upward first; the pitch unchanged when no transposition of it is available.
+ *
+ * @example
+ * ```ts
+ * import { BASS_4_STRING, foldIntoRange } from '@libraz/libcantus';
+ * foldIntoRange(27, BASS_4_STRING); // 39 — Eb1 is under the low E
+ * ```
+ * @category Core
+ */
+declare function foldIntoRange(pitch: number, profile: InstrumentProfile): number;
+
+/**
+ * Hierarchical seeds: one project number that addresses every part.
+ *
+ * A flat seed per generator makes the caller keep a table of numbers and,
+ * worse, makes "reroll the drums" mean "pick a number nobody else is using".
+ * Deriving instead — `deriveSeed(project, 'drums', 'chorus', 2)` — turns a
+ * reroll into an extra path segment, and every other part keeps the seed it
+ * had because its path did not change.
+ */
+/**
+ * The address of one derivation: a namespace, and whatever names or indices
+ * locate the thing being seeded.
+ *
+ * Strings and numbers are kept apart by the hash, so `'3'` and `3` address
+ * different things, as do `['ab', 'c']` and `['a', 'bc']`.
+ *
+ * @category Utilities
+ */
+type SeedPath = readonly (string | number)[];
+/**
+ * Derive a child seed from a root seed and a path.
+ *
+ * The result is a 32-bit integer, so it can be passed straight to
+ * {@link createRng}. Derivation is a pure function of its arguments — the same
+ * root and path give the same seed in every runtime — and near-identical paths
+ * (`'drums'` against `'drum'`, bar 1 against bar 2) give unrelated seeds: the
+ * path is hashed with FNV-1a and finished with the MurmurHash3 fmix32
+ * avalanche step.
+ *
+ * @param root The project seed; an integer in 0..0xffffffff.
+ * @param path The address to derive at; string or finite number segments.
+ * @returns The derived seed, an integer in 0..0xffffffff.
+ * @throws If the root is not a 32-bit integer, or a segment is neither a
+ * string nor a finite number.
+ * @example
+ * ```ts
+ * import { createRng, deriveSeed } from '@libraz/libcantus';
+ * const drums = deriveSeed(42, 'drums', 'chorus', 3);
+ * const rng = createRng(drums); // rerolling only the drums: bump the 3
+ * ```
+ * @category Utilities
+ */
+declare function deriveSeed(root: number, ...path: SeedPath): number;
+
+/**
+ * Position-addressed randomness and threshold sampling.
+ *
+ * Drawing in call order makes a generator's output depend on how many draws
+ * preceded it, so editing a parameter in the middle of a piece redraws
+ * everything after it. Addressing each draw by where it happens — bar, beat,
+ * voice — removes that coupling: the value at a position depends on the
+ * position alone, so a change anywhere leaves every other position as it was.
+ *
+ * Deciding inclusion by comparing a fixed positional draw against a complexity
+ * dial gives the property a slider needs: raising the dial only adds events,
+ * and everything already sounding stays where it was.
+ */
+
+/**
+ * A random source addressed by position rather than by call order.
+ *
+ * @category Utilities
+ */
+type PositionalRng = {
+    /**
+     * The draw belonging to a position: a float in [0, 1) that depends only on
+     * the seed and the path, so it is the same however often and in whatever
+     * order it is asked for.
+     */
+    at: (...path: SeedPath) => number;
+};
+/**
+ * Create a position-addressed random source.
+ *
+ * `at` holds no cursor: it is a pure function of the seed and the path, safe to
+ * call in any order, any number of times, from anywhere in a generator. Its
+ * draws are independent of {@link deriveSeed} at the same path, so a generator
+ * may seed a sub-part and take a positional draw at one position without
+ * getting the same number twice.
+ *
+ * @param seed The seed; an integer in 0..0xffffffff, typically from
+ * {@link deriveSeed}.
+ * @returns The positional source.
+ * @throws If the seed is not a 32-bit integer.
+ * @example
+ * ```ts
+ * import { createPositionalRng, deriveSeed } from '@libraz/libcantus';
+ * const rng = createPositionalRng(deriveSeed(42, 'drums'));
+ * rng.at('ghost', 4, 2.5); // the same value however often it is asked for
+ * ```
+ * @category Utilities
+ */
+declare function createPositionalRng(seed: number): PositionalRng;
+/**
+ * Whether the event at a position belongs in the output at a given complexity.
+ *
+ * The test is `at(...path) < complexity`, and because the draw is fixed by the
+ * position, the selected set grows monotonically with complexity: for any
+ * `c1 < c2` the events at `c1` are a subset of the events at `c2` over the same
+ * seed and the same path space. Complexity 0 selects nothing and complexity 1
+ * selects everything.
+ *
+ * @param rng The positional source; may be a caller-supplied one.
+ * @param complexity The dial, in [0, 1].
+ * @param path The position to test.
+ * @returns True when the position is included.
+ * @throws If the complexity is outside [0, 1], or the source returns a value
+ * outside [0, 1).
+ * @example
+ * ```ts
+ * import { createPositionalRng, includeAt } from '@libraz/libcantus';
+ * const rng = createPositionalRng(7);
+ * includeAt(rng, 0.3, 'ghost', 4, 2.5); // raising 0.3 only adds hits
+ * ```
+ * @category Utilities
+ */
+declare function includeAt(rng: PositionalRng, complexity: number, ...path: SeedPath): boolean;
+
+export { type InstrumentProfile as I, LIMBS as L, type PercussionProfile as P, type SeedPath as S, type InstrumentProfileCommon as a, type InstrumentProfileLike as b, type Limb as c, type PositionalRng as d, type StringFingering as e, type StringedProfile as f, canSound as g, createPositionalRng as h, deriveSeed as i, fingeringsFor as j, foldIntoRange as k, includeAt as l, instrumentRange as m };

package/dist/positional-DvH_sd8u.d.cts

@@ -0,0 +1,287 @@
+import { a as Articulation } from './index-B9MNZboQ.cjs';
+
+/**
+ * Every limb a percussionist strikes with, in declaration order.
+ *
+ * @category Core
+ */
+declare const LIMBS: readonly ["rightHand", "leftHand", "rightFoot", "leftFoot"];
+/**
+ * One limb of a percussionist.
+ *
+ * @category Core
+ */
+type Limb = (typeof LIMBS)[number];
+/**
+ * Fields every instrument profile carries, whatever its family.
+ *
+ * @category Core
+ */
+type InstrumentProfileCommon = {
+    /** Instrument name, for issue messages and for the caller's own display. */
+    name: string;
+    /** Techniques this instrument can produce; anything else it cannot play. */
+    articulations: readonly Articulation[];
+    /** Greatest number of notes that can sound at once. */
+    polyphony: number;
+};
+/**
+ * A fretted or fretless string instrument, described by what it is rather than
+ * by the range it happens to have.
+ *
+ * The sounding range follows from `tuning` and `frets`: string `s` sounds
+ * `tuning[s] .. tuning[s] + frets`. Storing `[min, max]` instead would make a
+ * five-string bass, a drop tuning, a seven-string guitar and an extended-range
+ * neck four unrelated special cases, and would leave "the neck is not long
+ * enough" indistinguishable from "the note is below the instrument".
+ *
+ * @category Core
+ */
+type StringedProfile = InstrumentProfileCommon & {
+    kind: 'stringed';
+    /** Open-string MIDI pitch per string, lowest-sounding string first. */
+    tuning: readonly number[];
+    /** Highest fret number; fret 0 is the open string. */
+    frets: number;
+    /** Greatest fret span one hand can hold down at once. */
+    maxStretch: number;
+    /**
+     * The neck has no frets. Positions are continuous, so intonation is the
+     * player's and a slide is unbroken; in twelve-tone equal temperament the
+     * positions coincide with fret numbers, so range and stretch are read the
+     * same way.
+     */
+    fretless?: boolean;
+};
+/**
+ * A percussion setup, described by the voices within reach of each limb.
+ *
+ * A kit's constraint is not range but limbs: a voice no limb can reach is not
+ * on the instrument, and two voices needing the same limb at the same instant
+ * cannot both sound.
+ *
+ * @category Core
+ */
+type PercussionProfile = InstrumentProfileCommon & {
+    kind: 'percussion';
+    /** The limbs the player has available. */
+    limbs: readonly Limb[];
+    /** Limbs that can strike each voice, in preference order, keyed by MIDI note. */
+    reach: Readonly<Record<number, readonly Limb[]>>;
+};
+/**
+ * An instrument the library can check a passage against.
+ *
+ * @category Core
+ */
+type InstrumentProfile = StringedProfile | PercussionProfile;
+/**
+ * Anything that names an instrument: a plain {@link InstrumentProfile}, or a
+ * value that serializes to one such as the `Instrument` class.
+ *
+ * Every entry point that takes an instrument takes this, so a caller holding
+ * the class hands it over as it is instead of unwrapping it for one call and
+ * wrapping it again for the next.
+ *
+ * @category Core
+ */
+type InstrumentProfileLike = InstrumentProfile | {
+    /** The profile data this value stands for. */
+    toJSON(): InstrumentProfile;
+};
+/**
+ * A fretting-hand position: which string, and how far up the neck.
+ *
+ * @category Core
+ */
+type StringFingering = {
+    /** Index into the `tuning` of a {@link StringedProfile}. */
+    string: number;
+    /** Fret number; 0 is the open string. */
+    fret: number;
+};
+/**
+ * The lowest and highest pitch an instrument sounds.
+ *
+ * For a string instrument this is derived from the tuning and the fret count,
+ * never stored; for a kit it is the extent of the voices the player's limbs
+ * reach. The range is not necessarily gapless — use {@link canSound} to ask
+ * about one pitch.
+ *
+ * @param profile The instrument.
+ * @returns The extreme sounding pitches, inclusive.
+ *
+ * @example
+ * ```ts
+ * import { BASS_5_STRING, instrumentRange } from '@libraz/libcantus';
+ * instrumentRange(BASS_5_STRING).low; // 23, low B
+ * ```
+ * @category Core
+ */
+declare function instrumentRange(profile: InstrumentProfile): {
+    low: number;
+    high: number;
+};
+/**
+ * Whether the instrument has this pitch at all.
+ *
+ * This is the first of the three playability layers: no amount of skill or
+ * rehearsal puts a note on an instrument that has no position for it.
+ *
+ * @param profile The instrument.
+ * @param pitch MIDI pitch.
+ * @returns True when some string and fret, or some limb the player has,
+ *   produces it.
+ * @category Core
+ */
+declare function canSound(profile: InstrumentProfile, pitch: number): boolean;
+/**
+ * Every position on the neck that sounds a pitch, lowest string first.
+ *
+ * @param profile The instrument.
+ * @param pitch MIDI pitch.
+ * @returns One entry per string that reaches the pitch; empty when none does.
+ * @category Core
+ */
+declare function fingeringsFor(profile: StringedProfile, pitch: number): StringFingering[];
+/**
+ * Move a pitch by whole octaves until the instrument can sound it.
+ *
+ * This is what a player does with a line written below the instrument: the note
+ * comes back an octave up, keeping its pitch class and its place in the phrase.
+ * Substituting a different scale degree, or refusing the passage outright, is
+ * the wrong answer for a bass line.
+ *
+ * @param pitch MIDI pitch to place.
+ * @param profile The instrument.
+ * @returns The nearest octave transposition the instrument sounds, searching
+ *   upward first; the pitch unchanged when no transposition of it is available.
+ *
+ * @example
+ * ```ts
+ * import { BASS_4_STRING, foldIntoRange } from '@libraz/libcantus';
+ * foldIntoRange(27, BASS_4_STRING); // 39 — Eb1 is under the low E
+ * ```
+ * @category Core
+ */
+declare function foldIntoRange(pitch: number, profile: InstrumentProfile): number;
+
+/**
+ * Hierarchical seeds: one project number that addresses every part.
+ *
+ * A flat seed per generator makes the caller keep a table of numbers and,
+ * worse, makes "reroll the drums" mean "pick a number nobody else is using".
+ * Deriving instead — `deriveSeed(project, 'drums', 'chorus', 2)` — turns a
+ * reroll into an extra path segment, and every other part keeps the seed it
+ * had because its path did not change.
+ */
+/**
+ * The address of one derivation: a namespace, and whatever names or indices
+ * locate the thing being seeded.
+ *
+ * Strings and numbers are kept apart by the hash, so `'3'` and `3` address
+ * different things, as do `['ab', 'c']` and `['a', 'bc']`.
+ *
+ * @category Utilities
+ */
+type SeedPath = readonly (string | number)[];
+/**
+ * Derive a child seed from a root seed and a path.
+ *
+ * The result is a 32-bit integer, so it can be passed straight to
+ * {@link createRng}. Derivation is a pure function of its arguments — the same
+ * root and path give the same seed in every runtime — and near-identical paths
+ * (`'drums'` against `'drum'`, bar 1 against bar 2) give unrelated seeds: the
+ * path is hashed with FNV-1a and finished with the MurmurHash3 fmix32
+ * avalanche step.
+ *
+ * @param root The project seed; an integer in 0..0xffffffff.
+ * @param path The address to derive at; string or finite number segments.
+ * @returns The derived seed, an integer in 0..0xffffffff.
+ * @throws If the root is not a 32-bit integer, or a segment is neither a
+ * string nor a finite number.
+ * @example
+ * ```ts
+ * import { createRng, deriveSeed } from '@libraz/libcantus';
+ * const drums = deriveSeed(42, 'drums', 'chorus', 3);
+ * const rng = createRng(drums); // rerolling only the drums: bump the 3
+ * ```
+ * @category Utilities
+ */
+declare function deriveSeed(root: number, ...path: SeedPath): number;
+
+/**
+ * Position-addressed randomness and threshold sampling.
+ *
+ * Drawing in call order makes a generator's output depend on how many draws
+ * preceded it, so editing a parameter in the middle of a piece redraws
+ * everything after it. Addressing each draw by where it happens — bar, beat,
+ * voice — removes that coupling: the value at a position depends on the
+ * position alone, so a change anywhere leaves every other position as it was.
+ *
+ * Deciding inclusion by comparing a fixed positional draw against a complexity
+ * dial gives the property a slider needs: raising the dial only adds events,
+ * and everything already sounding stays where it was.
+ */
+
+/**
+ * A random source addressed by position rather than by call order.
+ *
+ * @category Utilities
+ */
+type PositionalRng = {
+    /**
+     * The draw belonging to a position: a float in [0, 1) that depends only on
+     * the seed and the path, so it is the same however often and in whatever
+     * order it is asked for.
+     */
+    at: (...path: SeedPath) => number;
+};
+/**
+ * Create a position-addressed random source.
+ *
+ * `at` holds no cursor: it is a pure function of the seed and the path, safe to
+ * call in any order, any number of times, from anywhere in a generator. Its
+ * draws are independent of {@link deriveSeed} at the same path, so a generator
+ * may seed a sub-part and take a positional draw at one position without
+ * getting the same number twice.
+ *
+ * @param seed The seed; an integer in 0..0xffffffff, typically from
+ * {@link deriveSeed}.
+ * @returns The positional source.
+ * @throws If the seed is not a 32-bit integer.
+ * @example
+ * ```ts
+ * import { createPositionalRng, deriveSeed } from '@libraz/libcantus';
+ * const rng = createPositionalRng(deriveSeed(42, 'drums'));
+ * rng.at('ghost', 4, 2.5); // the same value however often it is asked for
+ * ```
+ * @category Utilities
+ */
+declare function createPositionalRng(seed: number): PositionalRng;
+/**
+ * Whether the event at a position belongs in the output at a given complexity.
+ *
+ * The test is `at(...path) < complexity`, and because the draw is fixed by the
+ * position, the selected set grows monotonically with complexity: for any
+ * `c1 < c2` the events at `c1` are a subset of the events at `c2` over the same
+ * seed and the same path space. Complexity 0 selects nothing and complexity 1
+ * selects everything.
+ *
+ * @param rng The positional source; may be a caller-supplied one.
+ * @param complexity The dial, in [0, 1].
+ * @param path The position to test.
+ * @returns True when the position is included.
+ * @throws If the complexity is outside [0, 1], or the source returns a value
+ * outside [0, 1).
+ * @example
+ * ```ts
+ * import { createPositionalRng, includeAt } from '@libraz/libcantus';
+ * const rng = createPositionalRng(7);
+ * includeAt(rng, 0.3, 'ghost', 4, 2.5); // raising 0.3 only adds hits
+ * ```
+ * @category Utilities
+ */
+declare function includeAt(rng: PositionalRng, complexity: number, ...path: SeedPath): boolean;
+
+export { type InstrumentProfile as I, LIMBS as L, type PercussionProfile as P, type SeedPath as S, type InstrumentProfileCommon as a, type InstrumentProfileLike as b, type Limb as c, type PositionalRng as d, type StringFingering as e, type StringedProfile as f, canSound as g, createPositionalRng as h, deriveSeed as i, fingeringsFor as j, foldIntoRange as k, includeAt as l, instrumentRange as m };