@scorelabs/core 1.0.5 → 1.0.9

package/dist/models/NoteSet.js

@@ -1,5 +1,5 @@
 import { Note } from './Note';
-import { Duration } from './types';
+import { Duration, } from './types';
 export class NoteSet {
     notes;
     constructor(notes) {
@@ -178,6 +178,9 @@ export class NoteSet {
     get slur() {
         return this.notes[0].slur;
     }
+    get articulations() {
+        return this.notes[0].articulations;
+    }
     get articulation() {
         return this.notes[0].articulation;
     }
@@ -264,7 +267,7 @@ export class NoteSet {
             return new NoteSet([new Note(Duration.Quarter, undefined, true)]);
         }
         let notesArray;
-        if (data.notes && Array.isArray(data.notes)) {
+        if ('notes' in data && Array.isArray(data.notes)) {
             notesArray = data.notes;
         }
         else if (Array.isArray(data)) {

package/dist/models/Part.d.ts

@@ -1,7 +1,7 @@
-import { Staff, StaffJSON } from './Staff';
 import { Instrument } from './Instrument';
-import { Note } from './Note';
 import { Measure } from './Measure';
+import { Note } from './Note';
+import { Staff, StaffJSON } from './Staff';
 import { Duration } from './types';
 /**
  * Represents a musical part (instrument/voice) which can have multiple staves.

package/dist/models/Part.js

@@ -1,5 +1,5 @@
-import { Staff } from './Staff';
 import { PRESET_INSTRUMENTS } from './Instrument';
+import { Staff } from './Staff';
 /**
  * Represents a musical part (instrument/voice) which can have multiple staves.
  */

package/dist/models/Pitch.js

@@ -33,7 +33,9 @@ export class Pitch {
     getStaffPosition(clef) {
         const middleLineAbsStep = {
             [Clef.Treble]: 4 * 7 + 6, // B4
+            [Clef.Treble8vaBassa]: 3 * 7 + 6, // B3
             [Clef.Bass]: 3 * 7 + 1, // D3
+            [Clef.Bass8vaBassa]: 2 * 7 + 1, // D2
             [Clef.Alto]: 4 * 7 + 0, // C4
             [Clef.Tenor]: 3 * 7 + 5, // A3
             [Clef.Percussion]: 4 * 7 + 6, // B4
@@ -100,7 +102,9 @@ export class Pitch {
     static fromStaffPosition(clef, staffPosition) {
         const middleLineAbsStep = {
             [Clef.Treble]: 4 * 7 + 6, // B4
+            [Clef.Treble8vaBassa]: 3 * 7 + 6, // B3
             [Clef.Bass]: 3 * 7 + 1, // D3
+            [Clef.Bass8vaBassa]: 2 * 7 + 1, // D2
             [Clef.Alto]: 4 * 7 + 0, // C4
             [Clef.Tenor]: 3 * 7 + 5, // A3
             [Clef.Percussion]: 4 * 7 + 0,

package/dist/models/PreMeasure.d.ts

@@ -0,0 +1,24 @@
+import { Clef, KeySignature, TimeSignature } from './types';
+export interface PreMeasureJSON {
+    clef?: string;
+    keySignature?: KeySignature;
+    timeSignature?: TimeSignature;
+}
+/**
+ * Represents the musical context before the first measure of a system.
+ * This includes the clef, key signature, and time signature.
+ */
+export declare class PreMeasure {
+    readonly clef?: Clef | undefined;
+    readonly keySignature?: KeySignature | undefined;
+    readonly timeSignature?: TimeSignature | undefined;
+    constructor(clef?: Clef | undefined, keySignature?: KeySignature | undefined, timeSignature?: TimeSignature | undefined);
+    /**
+     * Creates a PreMeasure from JSON data.
+     */
+    static fromJSON(data: Partial<PreMeasureJSON>): PreMeasure;
+    /**
+     * Converts the PreMeasure to a JSON-serializable object.
+     */
+    toJSON(): PreMeasureJSON;
+}

package/dist/models/PreMeasure.js

@@ -0,0 +1,30 @@
+/**
+ * Represents the musical context before the first measure of a system.
+ * This includes the clef, key signature, and time signature.
+ */
+export class PreMeasure {
+    clef;
+    keySignature;
+    timeSignature;
+    constructor(clef, keySignature, timeSignature) {
+        this.clef = clef;
+        this.keySignature = keySignature;
+        this.timeSignature = timeSignature;
+    }
+    /**
+     * Creates a PreMeasure from JSON data.
+     */
+    static fromJSON(data) {
+        return new PreMeasure(data.clef, data.keySignature, data.timeSignature);
+    }
+    /**
+     * Converts the PreMeasure to a JSON-serializable object.
+     */
+    toJSON() {
+        return {
+            clef: this.clef,
+            keySignature: this.keySignature,
+            timeSignature: this.timeSignature,
+        };
+    }
+}

package/dist/models/Score.d.ts

@@ -1,8 +1,8 @@
-import { TimeSignature, KeySignature, Duration, Genre } from './types';
+import { Measure } from './Measure';
+import { NoteSet } from './NoteSet';
 import { Part, PartJSON } from './Part';
 import { Staff } from './Staff';
-import { NoteSet } from './NoteSet';
-import { Measure } from './Measure';
+import { Clef, Duration, Genre, KeySignature, TimeSignature } from './types';
 /**
  * Represents a complete musical score.
  */
@@ -38,6 +38,21 @@ export declare class Score {
     static fromJSON(data: ScoreJSON): Score;
     transpose(semitones: number): Score;
     replaceNote(partIndex: number, staffIndex: number, measureIndex: number, noteIndex: number, newNote: NoteSet, voiceIndex?: number): Score;
+    withKeySignature(keySig: KeySignature): Score;
+    withTimeSignature(timeSig: TimeSignature): Score;
+    updateMeasureSignatures(measureIndex: number, signatures: {
+        keySignature?: KeySignature;
+        timeSignature?: TimeSignature;
+        clef?: Clef;
+    }, autoBeam?: boolean): Score;
+    /**
+     * Reflows the notes starting from a specific measure index.
+     * This is useful when time signatures change and notes need to be redistributed.
+     */
+    reflow(fromMeasureIndex: number, autoBeam?: boolean): Score;
+    private isTied;
+    private areSamePitch;
+    private reflowStaff;
     replaceMeasure(partIndex: number, staffIndex: number, measureIndex: number, newMeasure: Measure, autoBeam?: boolean): Score;
     deleteNote(partIndex: number, staffIndex: number, measureIndex: number, noteIndex: number, voiceIndex?: number): Score;
     changeNoteDuration(partIndex: number, staffIndex: number, measureIndex: number, noteIndex: number, newDuration: Duration, isDotted?: boolean, voiceIndex?: number): Score;

package/dist/models/Score.js

@@ -1,5 +1,6 @@
-import { Duration, decomposeDuration, Genre } from './types';
+import { Measure } from './Measure';
 import { Part } from './Part';
+import { Duration, Genre, decomposeDuration } from './types';
 /**
  * Represents a complete musical score.
  */
@@ -120,6 +121,170 @@ export class Score {
         const updatedMeasure = measure.replaceNoteSet(noteIndex, newNote, voiceIndex);
         return this.replaceMeasure(partIndex, staffIndex, measureIndex, updatedMeasure, true);
     }
+    withKeySignature(keySig) {
+        return new Score(this.title, this.composer, this.timeSignature, keySig, this.parts, this.bpm, this.tempoDuration, this.tempoIsDotted, this.copyright, this.lyricist, this.swing, this.subtitle, this.genre, this.tempoText);
+    }
+    withTimeSignature(timeSig) {
+        return new Score(this.title, this.composer, timeSig, this.keySignature, this.parts, this.bpm, this.tempoDuration, this.tempoIsDotted, this.copyright, this.lyricist, this.swing, this.subtitle, this.genre, this.tempoText);
+    }
+    updateMeasureSignatures(measureIndex, signatures, autoBeam = true) {
+        let score = this;
+        for (let pIdx = 0; pIdx < this.parts.length; pIdx++) {
+            for (let sIdx = 0; sIdx < this.parts[pIdx].staves.length; sIdx++) {
+                const currentMsr = score.parts[pIdx].staves[sIdx].measures[measureIndex];
+                if (currentMsr) {
+                    let updatedMsr = currentMsr;
+                    if (signatures.keySignature !== undefined) {
+                        updatedMsr = updatedMsr.withKeySignature(signatures.keySignature);
+                    }
+                    if (signatures.timeSignature !== undefined) {
+                        updatedMsr = updatedMsr.withTimeSignature(signatures.timeSignature);
+                    }
+                    if (signatures.clef !== undefined) {
+                        updatedMsr = updatedMsr.withClef(signatures.clef);
+                    }
+                    score = score.replaceMeasure(pIdx, sIdx, measureIndex, updatedMsr, autoBeam);
+                }
+            }
+        }
+        if (signatures.timeSignature !== undefined) {
+            score = score.reflow(measureIndex, autoBeam);
+        }
+        return score;
+    }
+    /**
+     * Reflows the notes starting from a specific measure index.
+     * This is useful when time signatures change and notes need to be redistributed.
+     */
+    reflow(fromMeasureIndex, autoBeam = true) {
+        let currentScore = this;
+        const allStaves = this.getAllStaves();
+        for (const { partIndex, staffIndex } of allStaves) {
+            currentScore = currentScore.reflowStaff(partIndex, staffIndex, fromMeasureIndex, autoBeam);
+        }
+        // Harmonize measure count across all staves
+        const maxMeasures = Math.max(...currentScore.parts.flatMap((p) => p.staves.map((s) => s.measures.length)));
+        const minMeasures = Math.min(...currentScore.parts.flatMap((p) => p.staves.map((s) => s.measures.length)));
+        if (maxMeasures !== minMeasures) {
+            for (let pIdx = 0; pIdx < currentScore.parts.length; pIdx++) {
+                for (let sIdx = 0; sIdx < currentScore.parts[pIdx].staves.length; sIdx++) {
+                    const staff = currentScore.parts[pIdx].staves[sIdx];
+                    if (staff.measures.length < maxMeasures) {
+                        let updatedMsrs = [...staff.measures];
+                        for (let i = staff.measures.length; i < maxMeasures; i++) {
+                            const ts = currentScore.getTimeSignatureAt(i);
+                            const targetDur = ts.beats * (4 / ts.beatType);
+                            updatedMsrs.push(new Measure([[]]).fillVoiceWithRests(0, targetDur));
+                        }
+                        currentScore = currentScore.replaceStaff(pIdx, sIdx, staff.withMeasures(updatedMsrs));
+                    }
+                }
+            }
+        }
+        return currentScore;
+    }
+    isTied(ns) {
+        return !!ns.notes[0].tie;
+    }
+    areSamePitch(ns1, ns2) {
+        if (ns1.isRest !== ns2.isRest)
+            return false;
+        if (ns1.isRest)
+            return true;
+        if (ns1.notes.length !== ns2.notes.length)
+            return false;
+        const p1 = ns1.notes.map((n) => n.pitch?.midiNumber || -1).sort((a, b) => a - b);
+        const p2 = ns2.notes.map((n) => n.pitch?.midiNumber || -1).sort((a, b) => a - b);
+        return p1.every((v, i) => v === p2[i]);
+    }
+    reflowStaff(pIdx, sIdx, fromMeasureIndex, autoBeam) {
+        const staff = this.parts[pIdx].staves[sIdx];
+        const measures = staff.measures;
+        const maxVoices = Math.max(...measures.map((m) => m.voices.length), 1);
+        let updatedMeasures = [...measures];
+        for (let vIdx = 0; vIdx < maxVoices; vIdx++) {
+            // 1. Collect notes and merge tied notes into logical streams
+            let stream = [];
+            for (let mIdx = fromMeasureIndex; mIdx < measures.length; mIdx++) {
+                const msr = measures[mIdx];
+                const voice = msr.voices[vIdx] || [];
+                for (const ns of voice) {
+                    const d = ns.getDurationValue();
+                    if (stream.length > 0 &&
+                        this.isTied(stream[stream.length - 1].ns) &&
+                        this.areSamePitch(stream[stream.length - 1].ns, ns)) {
+                        stream[stream.length - 1].duration += d;
+                    }
+                    else {
+                        stream.push({ ns, duration: d });
+                    }
+                }
+            }
+            // 2. Redistribute logical notes into measures according to time signatures
+            let currentMIdx = fromMeasureIndex;
+            let streamIdx = 0;
+            while (streamIdx < stream.length) {
+                if (currentMIdx >= updatedMeasures.length) {
+                    updatedMeasures.push(new Measure([[]]));
+                }
+                let msr = updatedMeasures[currentMIdx];
+                const ts = this.getTimeSignatureAt(currentMIdx);
+                const targetDur = ts.beats * (4 / ts.beatType);
+                const newVoices = [...msr.voices];
+                while (newVoices.length <= vIdx)
+                    newVoices.push([]);
+                newVoices[vIdx] = [];
+                msr = msr.withVoices(newVoices);
+                let currentDur = 0;
+                while (streamIdx < stream.length &&
+                    (currentDur < targetDur - 0.001 || stream[streamIdx].duration === 0)) {
+                    const logicalNote = stream[streamIdx];
+                    if (logicalNote.duration === 0) {
+                        // Grace note or zero-duration element
+                        msr = msr.withVoices(msr.voices.map((v, i) => (i === vIdx ? [...v, logicalNote.ns] : v)));
+                        streamIdx++;
+                        continue;
+                    }
+                    const remainingRoom = targetDur - currentDur;
+                    const toTake = Math.min(logicalNote.duration, remainingRoom);
+                    const parts = decomposeDuration(toTake);
+                    const newNoteSets = parts.map((p, idx) => {
+                        const isLastOfLogical = Math.abs(toTake - logicalNote.duration) < 0.001 && idx === parts.length - 1;
+                        return logicalNote.ns
+                            .withDuration(p.duration, p.isDotted)
+                            .withTie(isLastOfLogical ? !!logicalNote.ns.notes[0].tie : true);
+                    });
+                    msr = msr.withVoices(msr.voices.map((v, i) => (i === vIdx ? [...v, ...newNoteSets] : v)));
+                    logicalNote.duration -= toTake;
+                    currentDur += toTake;
+                    if (logicalNote.duration < 0.001) {
+                        streamIdx++;
+                    }
+                }
+                // Fill with rests if score is not full
+                if (currentDur < targetDur - 0.001) {
+                    msr = msr.fillVoiceWithRests(vIdx, targetDur);
+                }
+                if (autoBeam) {
+                    msr = msr.autoBeam(ts);
+                }
+                updatedMeasures[currentMIdx] = msr;
+                currentMIdx++;
+            }
+            // Ensure any remaining measures in this staff are also cleared/filled with rests for this voice
+            for (let mIdx = currentMIdx; mIdx < updatedMeasures.length; mIdx++) {
+                const ts = this.getTimeSignatureAt(mIdx);
+                const targetDur = ts.beats * (4 / ts.beatType);
+                updatedMeasures[mIdx] = updatedMeasures[mIdx]
+                    .withVoices(updatedMeasures[mIdx].voices.map((v, i) => (i === vIdx ? [] : v)))
+                    .fillVoiceWithRests(vIdx, targetDur);
+                if (autoBeam) {
+                    updatedMeasures[mIdx] = updatedMeasures[mIdx].autoBeam(ts);
+                }
+            }
+        }
+        return this.replaceStaff(pIdx, sIdx, staff.withMeasures(updatedMeasures));
+    }
     replaceMeasure(partIndex, staffIndex, measureIndex, newMeasure, autoBeam = true) {
         if (partIndex < 0 || partIndex >= this.parts.length)
             return this;
@@ -273,14 +438,27 @@ export class Score {
         const measures = this.parts[0]?.staves[0]?.measures || [];
         const sequence = [];
         let i = 0;
-        let blockStart = 0;
+        const startRepeatStack = [0]; // Implicit start at 0
+        let justJumpedTo = -1;
         const repeatCount = new Map();
-        while (i < measures.length) {
+        let safetyCounter = 0;
+        const MAX_SEQUENCE = 10000;
+        while (i < measures.length && safetyCounter < MAX_SEQUENCE) {
+            safetyCounter++;
             const m = measures[i];
-            if (m.repeats.some((r) => r.type === 'start'))
-                blockStart = i;
+            // Handle Start Repeats
+            if (m.repeats.some((r) => r.type === 'start')) {
+                // Only push if we didn't just jump here (avoid re-pushing on loop reentry)
+                if (i !== justJumpedTo) {
+                    startRepeatStack.push(i);
+                }
+            }
+            // Reset jump flag after processing start repeats check
+            if (i !== justJumpedTo)
+                justJumpedTo = -1;
             const endRepeat = m.repeats.find((r) => r.type === 'end');
             let iteration = 1;
+            // Calculate current iteration for Volta logic
             if (endRepeat)
                 iteration = (repeatCount.get(i) || 0) + 1;
             else {
@@ -294,7 +472,7 @@ export class Score {
                 if (nextEndIdx !== -1)
                     iteration = (repeatCount.get(nextEndIdx) || 0) + 1;
             }
-            if (m.volta && m.volta.number !== iteration) {
+            if (m.volta && !m.volta.numbers.includes(iteration)) {
                 i++;
                 continue;
             }
@@ -304,11 +482,21 @@ export class Score {
                 const currentCount = repeatCount.get(i) || 0;
                 if (currentCount + 1 < maxTimes) {
                     repeatCount.set(i, currentCount + 1);
-                    i = blockStart;
+                    // Jump to the nearest start repeat
+                    const target = startRepeatStack[startRepeatStack.length - 1];
+                    i = target;
+                    justJumpedTo = target;
                     continue;
                 }
-                else
+                else {
+                    // Finished loop
                     repeatCount.set(i, 0);
+                    // Pop the start repeat if we have one (keeping the implicit 0)
+                    if (startRepeatStack.length > 1) {
+                        startRepeatStack.pop();
+                    }
+                    // Do not pop 0, so unmatched repeats will default to 0
+                }
             }
             i++;
         }

package/dist/models/Staff.d.ts

@@ -1,7 +1,7 @@
-import { Clef, Duration } from './types';
 import { Measure, MeasureJSON } from './Measure';
-import { Pitch } from './Pitch';
 import { Note } from './Note';
+import { Pitch } from './Pitch';
+import { Clef, Duration } from './types';
 /**
  * Represents a single staff (one set of 5 lines with a clef).
  */

package/dist/models/index.d.ts

@@ -7,3 +7,4 @@ export * from './Staff';
 export * from './Part';
 export * from './Score';
 export * from './Instrument';
+export * from './PreMeasure';

package/dist/models/index.js

@@ -7,3 +7,4 @@ export * from './Staff';
 export * from './Part';
 export * from './Score';
 export * from './Instrument';
+export * from './PreMeasure';

package/dist/models/types.d.ts

@@ -1,216 +1,5 @@
 /**
  * Shared types and enums for ScoreLabs
+ * All types have been moved to ../types/ for better organization.
  */
-export declare enum StemDirection {
-    Up = "up",
-    Down = "down"
-}
-export declare enum Clef {
-    Treble = "treble",
-    Bass = "bass",
-    Alto = "alto",
-    Tenor = "tenor",
-    Percussion = "percussion",
-    Tab = "tab"
-}
-export declare enum Duration {
-    Whole = "whole",
-    Half = "half",
-    Quarter = "quarter",
-    Eighth = "eighth",
-    Sixteenth = "sixteenth",
-    ThirtySecond = "thirty-second",
-    SixtyFourth = "sixty-fourth",
-    OneHundredTwentyEighth = "one-hundred-twenty-eighth",
-    TwoHundredFiftySixth = "two-hundred-fifty-sixth"
-}
-export declare enum Accidental {
-    Sharp = "sharp",
-    Flat = "flat",
-    Natural = "natural",
-    DoubleSharp = "double-sharp",
-    DoubleFlat = "double-flat"
-}
-export declare enum Articulation {
-    Staccato = "staccato",
-    Accent = "accent",
-    Tenuto = "tenuto",
-    Marcato = "marcato",
-    Fermata = "fermata",
-    Staccatissimo = "staccatissimo",
-    Caesura = "caesura",
-    BreathMark = "breath-mark"
-}
-export declare enum Bowing {
-    DownBow = "down-bow",
-    UpBow = "up-bow"
-}
-export declare enum Syllabic {
-    Single = "single",
-    Begin = "begin",
-    Middle = "middle",
-    End = "end"
-}
-export interface Lyric {
-    text: string;
-    syllabic?: Syllabic;
-    isExtension?: boolean;
-}
-export declare enum NoteheadShape {
-    Normal = "normal",
-    Cross = "cross",// X shape (percussion, spoken)
-    Diamond = "diamond",// Harmonics
-    Slash = "slash",// Rhythmic notation
-    Triangle = "triangle",// Percussion
-    Square = "square"
-}
-export declare enum Dynamic {
-    PPP = "ppp",
-    PP = "pp",
-    P = "p",
-    MP = "mp",
-    MF = "mf",
-    F = "f",
-    FF = "ff",
-    FFF = "fff",
-    SFZ = "sfz",
-    FP = "fp"
-}
-export declare enum Genre {
-    Blues = "Blues",
-    Children = "Children",
-    Christian = "Christian",
-    Christmas = "Christmas",
-    Classical = "Classical",
-    ContestFestival = "Contest/Festival",
-    Country = "Country",
-    Educational = "Educational",
-    FilmTV = "Film/TV",
-    Folk = "Folk",
-    Games = "Games",
-    Gospel = "Gospel",
-    Holiday = "Holiday",
-    Jazz = "Jazz",
-    Latin = "Latin",
-    Musicals = "Musicals",
-    Pop = "Pop",
-    RBHipHop = "R&B/Hip-Hop",
-    Rock = "Rock",
-    Standards = "Standards",
-    Traditional = "Traditional",
-    Wedding = "Wedding",
-    World = "World",
-    Worship = "Worship",
-    Unknown = "unknown"
-}
-export interface TimeSignature {
-    beats: number;
-    beatType: number;
-    symbol?: 'common' | 'cut' | 'normal';
-}
-export interface KeySignature {
-    fifths: number;
-}
-export interface Tempo {
-    bpm: number;
-    duration: Duration;
-    isDotted: boolean;
-    text?: string;
-}
-export interface Slur {
-    placement: 'start' | 'stop';
-    direction?: 'up' | 'down';
-}
-export interface Tuplet {
-    actual: number;
-    normal: number;
-    type: 'start' | 'stop' | 'middle';
-}
-export declare enum HairpinType {
-    Crescendo = "crescendo",
-    Decrescendo = "decrescendo"
-}
-export interface Hairpin {
-    type: HairpinType;
-    placement: 'start' | 'stop';
-}
-export interface Repeat {
-    type: 'start' | 'end';
-    times?: number;
-}
-export interface Volta {
-    type: 'start' | 'stop' | 'both';
-    number: number;
-}
-export declare enum BarlineStyle {
-    Regular = "regular",
-    Double = "light-light",// Double barline (often used for key changes)
-    Final = "light-heavy",
-    Dotted = "dotted",
-    Dashed = "dashed",
-    Heavy = "heavy",
-    None = "none"
-}
-export declare enum GlissandoType {
-    Wavy = "wavy",
-    Straight = "straight"
-}
-export interface Glissando {
-    type: GlissandoType;
-    placement: 'start' | 'stop';
-}
-export declare enum Arpeggio {
-    Normal = "normal",
-    Up = "up",
-    Down = "down"
-}
-export declare enum OttavaType {
-    OttavaAlta = "8va",
-    OttavaBassa = "8vb",
-    QuindicesimaAlta = "15ma",
-    QuindicesimaBassa = "15mb"
-}
-export interface Ottava {
-    type: OttavaType;
-    placement: 'start' | 'stop';
-}
-export interface Pedal {
-    type: 'sustain' | 'una-corda';
-    placement: 'start' | 'stop';
-}
-export declare enum Ornament {
-    Trill = "trill",
-    Mordent = "mordent",
-    InvertedMordent = "inverted-mordent",
-    Turn = "turn",
-    InvertedTurn = "inverted-turn",
-    Tremolo = "tremolo"
-}
-export declare const DURATION_VALUES: Record<Duration, number>;
-/**
- * Decomposes a duration value (quarter = 1) into a list of duration/dot pairs.
- */
-export declare function decomposeDuration(value: number): {
-    duration: Duration;
-    isDotted: boolean;
-    val: number;
-}[];
-export interface FretboardDot {
-    string: number;
-    fret: number;
-    label?: string;
-}
-export interface FretboardBarre {
-    fret: number;
-    startString: number;
-    endString: number;
-}
-export interface FretboardDiagram {
-    strings: number;
-    frets: number;
-    startingFret?: number;
-    dots: FretboardDot[];
-    barres?: FretboardBarre[];
-    openStrings?: number[];
-    mutedStrings?: number[];
-}
+export * from '../types/index.js';