@sudobility/music_types 0.11.30 → 0.11.32

package/dist/domain/instruments/track-instrument.js

@@ -0,0 +1,102 @@
+import { gmInstrumentRange } from "./gm-range.js";
+import { gmMaxPolyphony, UNLIMITED_POLYPHONY } from "./gm-polyphony.js";
+import { gmWrittenTransposition } from "./gm-transposition.js";
+import { gmKit, gmKitAt } from "./gm-kit.js";
+import { GM_PERCUSSION_RANGE } from "./gm-percussion.js";
+import { gmInstrumentIcon, gmKitIcon } from "./gm-icon.js";
+import { gmInstrument } from "./gm.js";
+/** Whether `track`'s `midiProgram` addresses a drum kit rather than an instrument. */
+export function isPercussionTrack(track) {
+    return track.clef === "percussion";
+}
+/**
+ * The notes worth showing for `track` — General MIDI's drum range on a
+ * percussion track, the instrument's compass otherwise.
+ */
+export function trackKeyboardRange(track) {
+    if (isPercussionTrack(track))
+        return { ...GM_PERCUSSION_RANGE };
+    return gmInstrumentRange(track.midiProgram);
+}
+/**
+ * How many notes `track` can sound at once.
+ *
+ * Unlimited on a drum track: the limit exists to stop a part being written that
+ * nobody could play, and a kit is played with two hands and two feet across
+ * pieces that are all struck separately. Nothing about a kit address says
+ * otherwise.
+ */
+export function trackMaxPolyphony(track) {
+    if (isPercussionTrack(track))
+        return UNLIMITED_POLYPHONY;
+    return gmMaxPolyphony(track.midiProgram);
+}
+/**
+ * Semitones between `track`'s sounding and written pitch.
+ *
+ * Always zero on a drum track. A percussion staff's positions name drums, so
+ * transposing one does not move a part into a reader's key — it renames every
+ * drum in it.
+ */
+export function trackWrittenTransposition(track) {
+    if (isPercussionTrack(track))
+        return 0;
+    return gmWrittenTransposition(track.midiProgram);
+}
+/**
+ * `track`'s program, corrected to something its clef can actually mean.
+ *
+ * On a percussion track that is the kit whose region the address falls in; a
+ * MIDI file is free to set program 45 on channel 10, and the kit that resolves
+ * to is Brush. Off a percussion track the program is already an instrument and
+ * is returned untouched.
+ */
+export function trackProgramForClef(track) {
+    return isPercussionTrack(track)
+        ? gmKitAt(track.midiProgram).program
+        : track.midiProgram;
+}
+/** The icon for `track` — a kit on a percussion track, its instrument's art otherwise. */
+export function trackInstrumentIcon(track) {
+    return isPercussionTrack(track)
+        ? gmKitIcon()
+        : gmInstrumentIcon(track.midiProgram);
+}
+/** What to call `track`'s sound: its kit's name on a percussion track, its instrument's otherwise. */
+export function trackInstrumentLabel(track) {
+    if (isPercussionTrack(track))
+        return gmKitAt(track.midiProgram).name;
+    return gmInstrument(track.midiProgram)?.name ?? "Instrument";
+}
+/**
+ * `score` with every percussion track's program resolved to a real kit.
+ *
+ * A drum track can arrive holding an address no kit sits at: a MIDI file sets
+ * whatever program it likes on channel 10, and nothing before this treated that
+ * number as a kit at all. The picker would then have to show something the
+ * score does not say, so the score is corrected instead of the display fudged.
+ *
+ * A track already on a kit address is returned untouched — including its
+ * `instrumentName`, which is the user's description of a sound that is not
+ * changing. Only a track being corrected has its name rewritten, because the
+ * old one described a different kit.
+ *
+ * Returns the **identical object** when nothing needs correcting, which is the
+ * usual case: `computeLayout` is cached by score identity, and a fresh object
+ * on every load would also read as a change to the autosaver.
+ */
+export function scoreWithResolvedKits(score) {
+    const needsWork = score.tracks.some((track) => isPercussionTrack(track) && gmKit(track.midiProgram) === null);
+    if (!needsWork)
+        return score;
+    return {
+        ...score,
+        tracks: score.tracks.map((track) => {
+            if (!isPercussionTrack(track) || gmKit(track.midiProgram) !== null)
+                return track;
+            const kit = gmKitAt(track.midiProgram);
+            return { ...track, midiProgram: kit.program, instrumentName: kit.name };
+        }),
+    };
+}
+//# sourceMappingURL=track-instrument.js.map

package/dist/domain/instruments/track-instrument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-instrument.js","sourceRoot":"","sources":["../../../src/domain/instruments/track-instrument.ts"],"names":[],"mappings":"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"}

package/dist/domain/notation/chord-symbol.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Splitting a chord symbol into the parts MusicXML wants.
+ *
+ * The model stores the symbol as typed, because a lead sheet's vocabulary is
+ * wide and inconsistent and nothing a player writes should be refused. But
+ * MusicXML's `<harmony>` wants a `<root-step>` and an `<alter>` — so the root
+ * has to come out of the string for export, and only the root.
+ *
+ * The rest is carried verbatim as the kind's display text with `kind="other"`.
+ * That is a deliberate refusal to guess: mapping `-7`, `min7`, `m7`, `mi7` and
+ * `−7` onto MusicXML's enumeration is a dictionary that is wrong for somebody,
+ * and a symbol that round-trips as the exact text it was typed as is worth
+ * more here than one classified into a taxonomy. A reader that understands
+ * only the enumeration still sees the right root and the right printed text.
+ */
+/** What a chord symbol decomposes into. `null` when it does not start on a note letter. */
+export type ParsedChordSymbol = {
+    /** A–G. */
+    step: string;
+    /** -1 for flat, 1 for sharp, 0 for neither. */
+    alter: number;
+    /** Everything after the root, e.g. `maj7` or `-7/Bb`. May be empty. */
+    quality: string;
+};
+export declare function parseChordSymbol(symbol: string): ParsedChordSymbol | null;
+//# sourceMappingURL=chord-symbol.d.ts.map

package/dist/domain/notation/chord-symbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chord-symbol.d.ts","sourceRoot":"","sources":["../../../src/domain/notation/chord-symbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAezE"}

package/dist/domain/notation/chord-symbol.js

@@ -0,0 +1,32 @@
+/**
+ * Splitting a chord symbol into the parts MusicXML wants.
+ *
+ * The model stores the symbol as typed, because a lead sheet's vocabulary is
+ * wide and inconsistent and nothing a player writes should be refused. But
+ * MusicXML's `<harmony>` wants a `<root-step>` and an `<alter>` — so the root
+ * has to come out of the string for export, and only the root.
+ *
+ * The rest is carried verbatim as the kind's display text with `kind="other"`.
+ * That is a deliberate refusal to guess: mapping `-7`, `min7`, `m7`, `mi7` and
+ * `−7` onto MusicXML's enumeration is a dictionary that is wrong for somebody,
+ * and a symbol that round-trips as the exact text it was typed as is worth
+ * more here than one classified into a taxonomy. A reader that understands
+ * only the enumeration still sees the right root and the right printed text.
+ */
+const ROOT = /^([A-G])([#b♯♭]?)(.*)$/;
+export function parseChordSymbol(symbol) {
+    const match = ROOT.exec(symbol.trim());
+    if (!match)
+        return null;
+    const [, step, accidental, quality] = match;
+    return {
+        step,
+        alter: accidental === "#" || accidental === "♯"
+            ? 1
+            : accidental === "b" || accidental === "♭"
+                ? -1
+                : 0,
+        quality: quality.trim(),
+    };
+}
+//# sourceMappingURL=chord-symbol.js.map

package/dist/domain/notation/chord-symbol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chord-symbol.js","sourceRoot":"","sources":["../../../src/domain/notation/chord-symbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH,MAAM,IAAI,GAAG,wBAAwB,CAAC;AAEtC,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC;IAC5C,OAAO;QACL,IAAI;QACJ,KAAK,EACH,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,GAAG;YACtC,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,GAAG;gBACxC,CAAC,CAAC,CAAC,CAAC;gBACJ,CAAC,CAAC,CAAC;QACT,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/domain/notation/lyric-syllables.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How a typed syllable joins its neighbours.
+ *
+ * Its own module rather than living beside the entry bar: it is a pure rule
+ * about words, the entry bar is a component, and keeping them together costs
+ * that file its fast refresh.
+ */
+import type { Syllabic } from "../../index.js";
+/**
+ * Derived from whether the writer hyphenated this syllable and whether they
+ * hyphenated the one before — a writer knows they are in the middle of
+ * "beau-ti-ful" and should not also have to say so.
+ */
+export declare function syllabicFor(previousHyphenated: boolean, hyphenated: boolean): Syllabic;
+//# sourceMappingURL=lyric-syllables.d.ts.map

package/dist/domain/notation/lyric-syllables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lyric-syllables.d.ts","sourceRoot":"","sources":["../../../src/domain/notation/lyric-syllables.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,kBAAkB,EAAE,OAAO,EAC3B,UAAU,EAAE,OAAO,GAClB,QAAQ,CAKV"}

package/dist/domain/notation/lyric-syllables.js

@@ -0,0 +1,15 @@
+/**
+ * Derived from whether the writer hyphenated this syllable and whether they
+ * hyphenated the one before — a writer knows they are in the middle of
+ * "beau-ti-ful" and should not also have to say so.
+ */
+export function syllabicFor(previousHyphenated, hyphenated) {
+    if (previousHyphenated && hyphenated)
+        return "middle";
+    if (previousHyphenated)
+        return "end";
+    if (hyphenated)
+        return "begin";
+    return "single";
+}
+//# sourceMappingURL=lyric-syllables.js.map

package/dist/domain/notation/lyric-syllables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lyric-syllables.js","sourceRoot":"","sources":["../../../src/domain/notation/lyric-syllables.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,kBAA2B,EAC3B,UAAmB;IAEnB,IAAI,kBAAkB,IAAI,UAAU;QAAE,OAAO,QAAQ,CAAC;IACtD,IAAI,kBAAkB;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,UAAU;QAAE,OAAO,OAAO,CAAC;IAC/B,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/domain/notation/music-vocabulary.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Saying score values the way a musician says them.
+ *
+ * A score stores ticks, fifths and zero-based voice indexes because those are
+ * the right things to compute with. None of them is the right thing to *show*:
+ * a property panel that reads "Duration 480" and "Key (fifths) 2" is stating
+ * the storage format, and the reader has to convert in their head to know they
+ * are looking at a quarter note in D major.
+ *
+ * These are the conversions, kept in one place so every surface agrees — and
+ * kept here rather than in an app, because which tick count is a quarter note
+ * and how many sharps D major has are facts about music, not about a panel.
+ *
+ * No user-facing prose lives here: note values and key names are the terms of
+ * the domain, fixed across locales the way General MIDI's instrument names are.
+ */
+import type { Clef, DurationName, KeySignature, Pitch, Score } from "../../index.js";
+/** Every duration name, longest first, so a picker reads top to bottom. */
+export declare const DURATION_NAMES: DurationName[];
+/** What to call `name` in a picker. */
+export declare function durationLabel(name: DurationName): string;
+/** The number of sharps or flats a signature carries, as a phrase. */
+export declare function accidentalCountLabel(fifths: number): string;
+/** e.g. `D major`. Falls back to the fifths count for a signature outside ±7. */
+export declare function keySignatureName(key: KeySignature): string;
+/** Every key a picker should offer, from seven flats to seven sharps. */
+export declare function keySignatureOptions(mode: KeySignature["mode"]): Array<{
+    fifths: number;
+    label: string;
+}>;
+/**
+ * Where `tick` falls, counted the way a player counts: bar 1 upwards, beat 1
+ * upwards, with a fraction when it lands between beats.
+ *
+ * Read off the first track, since every track shares the measure grid once
+ * `rebuildMeasureTicks` has run. `null` when the score has no measures, or the
+ * tick lies past the end of them.
+ */
+export type BarBeat = {
+    bar: number;
+    beat: number;
+};
+export declare function barBeatForTick(score: Score, tick: number): BarBeat | null;
+/**
+ * The tick at `bar`/`beat`, both counted from 1. `null` when that bar does not
+ * exist; a beat past the end of its bar is clamped into it, because a typed
+ * "beat 9" in 4/4 means the end of the bar rather than an error.
+ */
+export declare function tickForBarBeat(score: Score, bar: number, beat: number): number | null;
+/**
+ * The pitch at a staff position, counted in half-spaces below the top line.
+ *
+ * `0` is the top line itself, `1` the space beneath it, `2` the next line down,
+ * and negative values are ledger positions above. Diatonic throughout, because
+ * a staff position names a letter rather than a semitone — what makes it an F♯
+ * rather than an F is the key signature, which is applied elsewhere.
+ */
+export declare function pitchAtStavePosition(clef: Clef, positionsBelowTopLine: number): Pitch;
+//# sourceMappingURL=music-vocabulary.d.ts.map

package/dist/domain/notation/music-vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"music-vocabulary.d.ts","sourceRoot":"","sources":["../../../src/domain/notation/music-vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EACV,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,KAAK,EAEN,MAAM,gBAAgB,CAAC;AAOxB,2EAA2E;AAC3E,eAAO,MAAM,cAAc,EAA6B,YAAY,EAAE,CAAC;AAuBvE,uCAAuC;AACvC,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAExD;AAyCD,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAI1D;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CASD;AAID;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA2BzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAef;AAuBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,IAAI,EACV,qBAAqB,EAAE,MAAM,GAC5B,KAAK,CAEP"}

package/dist/domain/notation/music-vocabulary.js

@@ -0,0 +1,164 @@
+import { DURATIONS, beatDurationTicks } from "../time/ticks.js";
+import { barNumberAt, indexOfBarNumber } from "../score/bar-numbers.js";
+import { shiftDiatonic } from "../pitch/transpose.js";
+// ---- durations -------------------------------------------------------------
+/** Every duration name, longest first, so a picker reads top to bottom. */
+export const DURATION_NAMES = Object.keys(DURATIONS);
+const DURATION_LABELS = {
+    whole: "Whole",
+    half: "Half",
+    quarter: "Quarter",
+    eighth: "Eighth",
+    sixteenth: "16th",
+    thirtysecond: "32nd",
+    "dotted-whole": "Dotted whole",
+    "dotted-half": "Dotted half",
+    "dotted-quarter": "Dotted quarter",
+    "dotted-eighth": "Dotted eighth",
+    "dotted-sixteenth": "Dotted 16th",
+    "dotted-thirtysecond": "Dotted 32nd",
+    "triplet-whole": "Whole triplet",
+    "triplet-half": "Half triplet",
+    "triplet-quarter": "Quarter triplet",
+    "triplet-eighth": "Eighth triplet",
+    "triplet-sixteenth": "16th triplet",
+    "triplet-thirtysecond": "32nd triplet",
+};
+/** What to call `name` in a picker. */
+export function durationLabel(name) {
+    return DURATION_LABELS[name];
+}
+// ---- key signatures --------------------------------------------------------
+/** Sharps are positive, flats negative — the MusicXML convention the model stores. */
+const MAJOR_KEYS = {
+    [-7]: "C♭",
+    [-6]: "G♭",
+    [-5]: "D♭",
+    [-4]: "A♭",
+    [-3]: "E♭",
+    [-2]: "B♭",
+    [-1]: "F",
+    0: "C",
+    1: "G",
+    2: "D",
+    3: "A",
+    4: "E",
+    5: "B",
+    6: "F♯",
+    7: "C♯",
+};
+const MINOR_KEYS = {
+    [-7]: "A♭",
+    [-6]: "E♭",
+    [-5]: "B♭",
+    [-4]: "F",
+    [-3]: "C",
+    [-2]: "G",
+    [-1]: "D",
+    0: "A",
+    1: "E",
+    2: "B",
+    3: "F♯",
+    4: "C♯",
+    5: "G♯",
+    6: "D♯",
+    7: "A♯",
+};
+/** The number of sharps or flats a signature carries, as a phrase. */
+export function accidentalCountLabel(fifths) {
+    if (fifths === 0)
+        return "no sharps or flats";
+    const count = Math.abs(fifths);
+    const kind = fifths > 0 ? "sharp" : "flat";
+    return `${count} ${kind}${count === 1 ? "" : "s"}`;
+}
+/** e.g. `D major`. Falls back to the fifths count for a signature outside ±7. */
+export function keySignatureName(key) {
+    const table = key.mode === "minor" ? MINOR_KEYS : MAJOR_KEYS;
+    const tonic = table[key.fifths];
+    return tonic ? `${tonic} ${key.mode}` : `${key.fifths} fifths`;
+}
+/** Every key a picker should offer, from seven flats to seven sharps. */
+export function keySignatureOptions(mode) {
+    const table = mode === "minor" ? MINOR_KEYS : MAJOR_KEYS;
+    return Object.keys(table)
+        .map(Number)
+        .sort((a, b) => a - b)
+        .map((fifths) => ({
+        fifths,
+        label: `${table[fifths]} ${mode} — ${accidentalCountLabel(fifths)}`,
+    }));
+}
+export function barBeatForTick(score, tick) {
+    const track = score.tracks[0];
+    if (!track || track.measures.length === 0)
+        return null;
+    const measure = track.measures.find((m) => tick >= m.startTick && tick < m.startTick + m.durationTicks);
+    if (!measure)
+        return null;
+    const beatTicks = beatDurationTicks(measure.timeSignature, score.ppq);
+    /*
+      Through `barNumberAt`, not `index + 1`: a pickup is not counted, so every
+      bar after one is a bar lower than its position. The readout has to say the
+      number the player's part says, or "go to bar 33" and the bar shown in the
+      inspector mean two different places.
+  
+      A pickup itself has no number; it reports bar 0, which is what a player
+      calls it when they have to call it something.
+    */
+    const index = track.measures.indexOf(measure);
+    return {
+        bar: barNumberAt(track.measures, index) ?? 0,
+        beat: (tick - measure.startTick) / beatTicks + 1,
+    };
+}
+/**
+ * The tick at `bar`/`beat`, both counted from 1. `null` when that bar does not
+ * exist; a beat past the end of its bar is clamped into it, because a typed
+ * "beat 9" in 4/4 means the end of the bar rather than an error.
+ */
+export function tickForBarBeat(score, bar, beat) {
+    const track = score.tracks[0];
+    if (!track)
+        return null;
+    // The inverse of the numbering above, so a typed bar number and a displayed
+    // one always name the same bar.
+    const index = indexOfBarNumber(track.measures, Math.round(bar));
+    const measure = index === null ? undefined : track.measures[index];
+    if (!measure)
+        return null;
+    const beatTicks = beatDurationTicks(measure.timeSignature, score.ppq);
+    const offset = Math.max(0, (beat - 1) * beatTicks);
+    return measure.startTick + Math.min(offset, measure.durationTicks - 1);
+}
+// ---- staff positions -------------------------------------------------------
+/**
+ * The pitch printed on each clef's top staff line.
+ *
+ * Everything a click on the stave means is measured from here: a staff
+ * position is a line or the space below it, and the pitch is that many
+ * diatonic steps down from this note.
+ *
+ * Percussion has no pitch — a drum staff's lines are instruments, not notes —
+ * so it borrows treble's geometry and the caller decides what a position means
+ * on it.
+ */
+const TOP_LINE_PITCH = {
+    treble: { step: "F", accidental: 0, octave: 5 },
+    bass: { step: "A", accidental: 0, octave: 3 },
+    alto: { step: "G", accidental: 0, octave: 4 },
+    tenor: { step: "E", accidental: 0, octave: 4 },
+    percussion: { step: "F", accidental: 0, octave: 5 },
+};
+/**
+ * The pitch at a staff position, counted in half-spaces below the top line.
+ *
+ * `0` is the top line itself, `1` the space beneath it, `2` the next line down,
+ * and negative values are ledger positions above. Diatonic throughout, because
+ * a staff position names a letter rather than a semitone — what makes it an F♯
+ * rather than an F is the key signature, which is applied elsewhere.
+ */
+export function pitchAtStavePosition(clef, positionsBelowTopLine) {
+    return shiftDiatonic(TOP_LINE_PITCH[clef], -positionsBelowTopLine);
+}
+//# sourceMappingURL=music-vocabulary.js.map

package/dist/domain/notation/music-vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"music-vocabulary.js","sourceRoot":"","sources":["../../../src/domain/notation/music-vocabulary.ts"],"names":[],"mappings":"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"}

package/dist/domain/pitch/pitch.d.ts

@@ -1,4 +1,4 @@
-import type { KeySignature, Pitch } from '../../index.js';
+import type { KeySignature, Pitch } from "../../index.js";
 /** Converts a `Pitch` to its MIDI note number (C4 = 60, A4 = 69). */
 export declare function pitchToMidi(p: Pitch): number;
 /**

package/dist/domain/pitch/pitch.js

@@ -20,33 +20,33 @@ export function pitchToMidi(p) {
 }
 /** step/accidental spelling for each pitch class 0-11, preferring sharps. */
 const SHARP_SPELLING = [
-    { step: 'C', accidental: 0 },
-    { step: 'C', accidental: 1 },
-    { step: 'D', accidental: 0 },
-    { step: 'D', accidental: 1 },
-    { step: 'E', accidental: 0 },
-    { step: 'F', accidental: 0 },
-    { step: 'F', accidental: 1 },
-    { step: 'G', accidental: 0 },
-    { step: 'G', accidental: 1 },
-    { step: 'A', accidental: 0 },
-    { step: 'A', accidental: 1 },
-    { step: 'B', accidental: 0 },
+    { step: "C", accidental: 0 },
+    { step: "C", accidental: 1 },
+    { step: "D", accidental: 0 },
+    { step: "D", accidental: 1 },
+    { step: "E", accidental: 0 },
+    { step: "F", accidental: 0 },
+    { step: "F", accidental: 1 },
+    { step: "G", accidental: 0 },
+    { step: "G", accidental: 1 },
+    { step: "A", accidental: 0 },
+    { step: "A", accidental: 1 },
+    { step: "B", accidental: 0 },
 ];
 /** step/accidental spelling for each pitch class 0-11, preferring flats. */
 const FLAT_SPELLING = [
-    { step: 'C', accidental: 0 },
-    { step: 'D', accidental: -1 },
-    { step: 'D', accidental: 0 },
-    { step: 'E', accidental: -1 },
-    { step: 'E', accidental: 0 },
-    { step: 'F', accidental: 0 },
-    { step: 'G', accidental: -1 },
-    { step: 'G', accidental: 0 },
-    { step: 'A', accidental: -1 },
-    { step: 'A', accidental: 0 },
-    { step: 'B', accidental: -1 },
-    { step: 'B', accidental: 0 },
+    { step: "C", accidental: 0 },
+    { step: "D", accidental: -1 },
+    { step: "D", accidental: 0 },
+    { step: "E", accidental: -1 },
+    { step: "E", accidental: 0 },
+    { step: "F", accidental: 0 },
+    { step: "G", accidental: -1 },
+    { step: "G", accidental: 0 },
+    { step: "A", accidental: -1 },
+    { step: "A", accidental: 0 },
+    { step: "B", accidental: -1 },
+    { step: "B", accidental: 0 },
 ];
 /**
  * Converts a MIDI note number to a `Pitch`, choosing an enharmonic spelling
@@ -63,11 +63,11 @@ export function midiToPitch(midi, keySignature) {
     return { step, accidental, octave };
 }
 const ACCIDENTAL_SYMBOLS = {
-    [-2]: 'bb',
-    [-1]: 'b',
-    [0]: '',
-    [1]: '#',
-    [2]: '##',
+    [-2]: "bb",
+    [-1]: "b",
+    [0]: "",
+    [1]: "#",
+    [2]: "##",
 };
 /** Formats a `Pitch` as a string, e.g. `C4`, `F#3`, `Bb4`, `F##4`. */
 export function pitchToString(p) {

package/dist/domain/pitch/transpose.d.ts

@@ -1,4 +1,4 @@
-import type { KeySignature, Pitch } from '../../index.js';
+import type { KeySignature, Pitch } from "../../index.js";
 /**
  * Transposes a pitch by a number of semitones (may be negative), re-spelling
  * the result according to the given key signature (see `midiToPitch`).

package/dist/domain/pitch/transpose.js

@@ -1,4 +1,4 @@
-import { midiToPitch, pitchToMidi } from './pitch.js';
+import { midiToPitch, pitchToMidi } from "./pitch.js";
 /**
  * Transposes a pitch by a number of semitones (may be negative), re-spelling
  * the result according to the given key signature (see `midiToPitch`).
@@ -14,7 +14,7 @@ export function transposeDiatonicOctave(p, octaves) {
     return { ...p, octave: p.octave + octaves };
 }
 /** The seven letter names, in order, for diatonic movement. */
-const STEPS = ['C', 'D', 'E', 'F', 'G', 'A', 'B'];
+const STEPS = ["C", "D", "E", "F", "G", "A", "B"];
 /**
  * Moves `p` by `steps` positions on the staff — one step per line-to-adjacent-
  * space — keeping its accidental.

package/dist/domain/quantization/quantize.d.ts

@@ -1,5 +1,5 @@
-import type { MusicalEvent } from '../../index.js';
-import type { QuantizeOptions } from './options.js';
+import type { MusicalEvent } from "../../index.js";
+import type { QuantizeOptions } from "./options.js";
 /**
  * Quantizes `events` per `opts` (spec §24): drops undersized notes, snaps
  * starts (grid/triplet/swing/humanize tolerance) and durations (grid,

package/dist/domain/quantization/quantize.js

@@ -5,8 +5,8 @@
  * means a deterministic "already close enough, leave it" tolerance, not
  * random jitter). Exposed for both MIDI import cleanup and manual editing.
  */
-import { createId } from '../score/ids.js';
-import { isNoteEvent } from '../../index.js';
+import { createId } from "../score/ids.js";
+import { isNoteEvent } from "../../index.js";
 /** `tripletGrid` subdivides `grid` into thirds-of-two (2/3 of `grid`); otherwise the grid unit is used as-is. */
 function effectiveGridTicks(opts) {
     return opts.tripletGrid ? (opts.grid * 2) / 3 : opts.grid;
@@ -53,7 +53,7 @@ function computeSnappedDuration(original, opts) {
 function dropShortNotes(events, minDurationTicks) {
     if (minDurationTicks === undefined)
         return events;
-    return events.filter(event => !isNoteEvent(event) || event.durationTicks >= minDurationTicks);
+    return events.filter((event) => !isNoteEvent(event) || event.durationTicks >= minDurationTicks);
 }
 /** Groups events by (trackId, voiceId), preserving each group's first-seen order. */
 function groupByVoice(events) {
@@ -69,7 +69,7 @@ function groupByVoice(events) {
         }
         group.push(event);
     }
-    return order.map(key => groups.get(key));
+    return order.map((key) => groups.get(key));
 }
 /**
  * Clusters near-simultaneous onsets (already sorted by `startTick`) onto a
@@ -101,7 +101,7 @@ function applyChordGrouping(sorted, tolerance) {
  * into the next one" meaning of overlap resolution.
  */
 function applyResolveOverlaps(sorted) {
-    const result = sorted.map(event => ({ ...event }));
+    const result = sorted.map((event) => ({ ...event }));
     for (let i = 0; i < result.length - 1; i += 1) {
         const current = result[i];
         const next = result[i + 1];
@@ -121,7 +121,7 @@ function applyResolveOverlaps(sorted) {
  * next one. Events sharing an exact start tick (a chord) are left alone.
  */
 function applyLegatoCleanup(sorted) {
-    const result = sorted.map(event => ({ ...event }));
+    const result = sorted.map((event) => ({ ...event }));
     for (let i = 0; i < result.length - 1; i += 1) {
         const current = result[i];
         const next = result[i + 1];
@@ -183,17 +183,17 @@ function processVoiceGroup(group, opts) {
  */
 export function quantizeEvents(events, opts) {
     const survivors = dropShortNotes(events, opts.minDurationTicks);
-    const withStarts = survivors.map(event => opts.quantizeStarts
+    const withStarts = survivors.map((event) => opts.quantizeStarts
         ? { ...event, startTick: computeSnappedStart(event.startTick, opts) }
         : { ...event });
-    const withDurations = withStarts.map(event => opts.quantizeDurations
+    const withDurations = withStarts.map((event) => opts.quantizeDurations
         ? {
             ...event,
             durationTicks: computeSnappedDuration(event.durationTicks, opts),
         }
         : event);
     return groupByVoice(withDurations)
-        .map(group => processVoiceGroup(group, opts))
+        .map((group) => processVoiceGroup(group, opts))
         .flat();
 }
 //# sourceMappingURL=quantize.js.map