@scorelabs/viewer 1.0.1

package/dist/importers/MusicXMLParser.d.ts

@@ -0,0 +1,51 @@
+import { ScoreJSON } from '../models/Score';
+/**
+ * MusicXML Parser class
+ */
+export declare class MusicXMLParser {
+    private currentKeyFifths;
+    private currentBeats;
+    private currentBeatType;
+    /**
+     * Parse a MusicXML string and return ScoreJSON
+     */
+    parse(xmlString: string): ScoreJSON;
+    /**
+     * Parse work title or movement title
+     */
+    private parseTitle;
+    /**
+     * Parse composer from identification/creator
+     */
+    private parseComposer;
+    /**
+     * Parse part-list to get part names
+     */
+    private parsePartList;
+    /**
+     * Parse a single part into multiple staves if present
+     */
+    /**
+     * Parse all parts
+     */
+    private parseParts;
+    /**
+     * Parse a single part into multiple staves if present
+     */
+    private parsePart;
+    /**
+     * Parse a single note element
+     */
+    private parseNote;
+    private stepToNumber;
+    /**
+     * Professional Musical Post-Processing
+     */
+    postProcess(score: ScoreJSON): ScoreJSON;
+    private cleanAccidentals;
+    private applyBeaming;
+}
+/**
+ * Utility function to load and parse a MusicXML file
+ */
+export declare function loadMusicXML(url: string): Promise<ScoreJSON>;

package/dist/importers/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Importers module
+ *
+ * Provides utilities for importing various music file formats into Score format.
+ */
+export { MusicXMLParser, loadMusicXML } from './MusicXMLParser';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './src/index'
+export {}

package/dist/layouts/LayoutConfig.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Layout engine configuration
+ */
+export interface LayoutConfig {
+    canvasWidth: number;
+    marginTop: number;
+    marginLeft: number;
+    marginRight: number;
+    marginBottom: number;
+    titleHeight: number;
+    staffLineSpacing: number;
+    staffMargin: number;
+    systemMargin: number;
+    measuresPerLine: number;
+    clefWidth: number;
+    trebleClefYOffset: number;
+    bassClefYOffset: number;
+    noteDotDistance: number;
+    titleSubtitleSpacing: number;
+    subtitleScoreSpacing: number;
+    minNoteSpacing: number;
+    firstSystemIndentation: number;
+    musicFont: 'Standard' | 'Jazz';
+    showMeasureNumbers: boolean;
+    measureNumberMode: 'system' | 'interval' | 'measure';
+    measureNumberInterval: number;
+    showPartNames: boolean;
+    groupMultiMeasureRests: boolean;
+    titleStyle: TextStyle;
+    subtitleStyle: TextStyle;
+    composerStyle: TextStyle;
+    pageWidth: number;
+    pageHeight: number;
+    tempoStyle: TextStyle;
+    clefKeySignatureSpacing: number;
+    noteNameMode: 'none' | 'alphabetical' | 'solfege';
+    bassClefScale: number;
+    trebleClefScale: number;
+    clefLeftPadding: number;
+    midMeasureClefWidth: number;
+    keySignatureStepWidth: number;
+    keySignatureRightPadding: number;
+    timeSignatureWidth: number;
+}
+/**
+ * Text style configuration
+ */
+export interface TextStyle {
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: 'normal' | 'bold';
+    fontStyle: 'normal' | 'italic';
+}
+/**
+ * Default layout configuration
+ */
+export declare const DEFAULT_LAYOUT_CONFIG: LayoutConfig;
+/**
+ * Resolves a LayoutConfig by multiplying all relative values by staffLineSpacing.
+ * This ensures that proportions remain constant as staffLineSpacing (zoom) changes.
+ */
+export declare function resolveLayoutConfig(config: LayoutConfig): LayoutConfig;

package/dist/layouts/LayoutUtils.d.ts

@@ -0,0 +1,10 @@
+import { Clef } from '../models/types';
+import { LayoutConfig } from './LayoutConfig';
+/**
+ * Calculates the width of a clef symbol based on configuration.
+ */
+export declare function getClefWidth(clef: Clef, config: LayoutConfig): number;
+/**
+ * Calculates the width of a key signature based on number of accidentals.
+ */
+export declare function getKeySignatureWidth(fifths: number, config: LayoutConfig): number;

package/dist/layouts/MeasureLayout.d.ts

@@ -0,0 +1,20 @@
+import { Measure } from '../models';
+import { Clef, TimeSignature } from '../models/types';
+import { NoteLayout } from './NoteLayout';
+import { LayoutConfig } from './LayoutConfig';
+/**
+ * Layout information for a measure.
+ */
+export interface MeasureLayout {
+    measure: Measure;
+    x: number;
+    width: number;
+    voiceLayouts: NoteLayout[][];
+    noteLayouts: NoteLayout[];
+    measureNumber: number;
+    signatureWidth?: number;
+}
+/**
+ * Calculate measure layout
+ */
+export declare function calculateMeasureLayout(measure: Measure, measureNumber: number, x: number, width: number, staffY: number, clef: Clef, currentTimeSignature: TimeSignature, config: LayoutConfig, lineCount?: number): MeasureLayout;

package/dist/layouts/NoteLayout.d.ts

@@ -0,0 +1,21 @@
+import { Note } from '../models';
+import { Clef, StemDirection } from '../models/types';
+/**
+ * Layout information for a single note.
+ */
+export interface NoteLayout {
+    note: Note;
+    x: number;
+    y: number;
+    staffPosition: number;
+    stemDirection: StemDirection;
+    stemStartY: number;
+    stemEndY: number;
+    clef: Clef;
+    voiceIndex: number;
+    noteIndex: number;
+}
+/**
+ * Calculate note layout
+ */
+export declare function calculateNoteLayout(note: Note, x: number, staffY: number, staffLineSpacing: number, clef: Clef, lineCount?: number, voiceIndex?: number, noteIndex?: number): NoteLayout;

package/dist/layouts/ScoreLayout.d.ts

@@ -0,0 +1,28 @@
+import { Score } from '../models';
+import { StaffSystemLayout } from './StaffSystemLayout';
+import { LayoutConfig } from './LayoutConfig';
+/**
+ * Layout for a single page.
+ */
+export interface PageLayout {
+    width: number;
+    height: number;
+    systemLayouts: StaffSystemLayout[];
+    titleY?: number;
+    subtitleY?: number;
+    composerY?: number;
+    lyricistY?: number;
+    copyrightY?: number;
+}
+/**
+ * Top-level layout for the entire score.
+ */
+export interface ScoreLayout {
+    pages: PageLayout[];
+    totalWidth: number;
+    totalHeight: number;
+}
+/**
+ * Calculate complete score layout distributed across pages
+ */
+export declare function calculateScoreLayout(score: Score, configRaw?: LayoutConfig, visiblePartIndices?: number[]): ScoreLayout;

package/dist/layouts/StaffLayout.d.ts

@@ -0,0 +1,26 @@
+import { Staff } from '../models';
+import { Clef, KeySignature, TimeSignature } from '../models/types';
+import { MeasureLayout } from './MeasureLayout';
+import { LayoutConfig } from './LayoutConfig';
+/**
+ * Layout information for a staff.
+ */
+export interface StaffLayout {
+    staff: Staff;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    clef: Clef;
+    measureLayouts: MeasureLayout[];
+    partIndex: number;
+    staffIndex: number;
+    keySignature: KeySignature;
+    timeSignature: TimeSignature;
+    maxClefWidth: number;
+    maxKeySignatureWidth: number;
+}
+/**
+ * Calculate staff layout
+ */
+export declare function calculateStaffLayout(staff: Staff, partIndex: number, staffIndex: number, x: number, y: number, width: number, measureStartIndex: number, measuresPerLine: number, keySignature: KeySignature, timeSignature: TimeSignature, config: LayoutConfig, measureNumberStartIndex?: number, maxClefWidth?: number, maxKeySignatureWidth?: number, measureWidths?: number[]): StaffLayout;

package/dist/layouts/StaffSystemLayout.d.ts

@@ -0,0 +1,18 @@
+import { Score } from '../models';
+import { StaffLayout } from './StaffLayout';
+import { KeySignature, TimeSignature } from '../models/types';
+import { LayoutConfig } from './LayoutConfig';
+/**
+ * Layout for a staff system (one horizontal row of staves).
+ */
+export interface StaffSystemLayout {
+    y: number;
+    height: number;
+    staffLayouts: StaffLayout[];
+    measureStartIndex: number;
+    measuresInSystem: number;
+}
+/**
+ * Calculate staff system layout
+ */
+export declare function calculateStaffSystemLayout(score: Score, x: number, y: number, width: number, measureStartIndex: number, measuresPerLine: number, keySignature: KeySignature, timeSignature: TimeSignature, config: LayoutConfig, measureNumberStartIndex?: number): StaffSystemLayout;

package/dist/layouts/index.d.ts

@@ -0,0 +1,6 @@
+export * from './NoteLayout';
+export * from './MeasureLayout';
+export * from './StaffLayout';
+export * from './StaffSystemLayout';
+export * from './ScoreLayout';
+export * from './LayoutConfig';

package/dist/models/Instrument.d.ts

@@ -0,0 +1,26 @@
+export declare enum InstrumentType {
+    String = "string",
+    Brass = "brass",
+    Woodwind = "woodwind",
+    Percussion = "percussion",
+    Keyboard = "keyboard",
+    Synth = "synth"
+}
+export declare enum InstrumentPreset {
+    Piano = "piano",
+    Violin = "violin",
+    Cello = "cello",
+    Guitar = "guitar",
+    ElectricGuitar = "electric-guitar",
+    Bass = "bass",
+    Flute = "flute",
+    Trumpet = "trumpet",
+    Drums = "drums"
+}
+export interface Instrument {
+    name: string;
+    midiProgram: number;
+    type?: InstrumentType;
+}
+export declare const PRESET_INSTRUMENTS: Record<string, Instrument>;
+export declare function getInstrumentByProgram(program: number): Instrument;

package/dist/models/Measure.d.ts

@@ -0,0 +1,80 @@
+import { Note, NoteJSON } from './Note';
+import { TimeSignature, KeySignature, Duration, Repeat, Volta, Clef, Tempo } from './types';
+/**
+ * Represents a single measure containing notes, potentially in multiple voices.
+ */
+export declare class Measure {
+    readonly voices: Note[][];
+    readonly timeSignature?: TimeSignature | undefined;
+    readonly keySignature?: KeySignature | undefined;
+    readonly systemBreak: boolean;
+    readonly pageBreak: boolean;
+    readonly repeats: Repeat[];
+    readonly volta?: Volta | undefined;
+    readonly isPickup: boolean;
+    readonly clef?: Clef | undefined;
+    readonly tempo?: Tempo | undefined;
+    readonly rehearsalMark?: string | undefined;
+    readonly systemText?: string | undefined;
+    constructor(voices: Note[][], timeSignature?: TimeSignature | undefined, // Only if changes mid-piece
+    keySignature?: KeySignature | undefined, // Only if changes mid-piece
+    systemBreak?: boolean, pageBreak?: boolean, repeats?: Repeat[], volta?: Volta | undefined, isPickup?: boolean, clef?: Clef | undefined, tempo?: Tempo | undefined, rehearsalMark?: string | undefined, systemText?: string | undefined);
+    /**
+     * Backward compatibility property for single-voice logic.
+     * Returns the first voice.
+     */
+    get notes(): Note[];
+    /**
+     * Change the duration of a note in a specific voice
+     */
+    changeNoteDuration(noteIndex: number, newDuration: Duration, isDotted?: boolean, voiceIndex?: number): Measure;
+    getTotalDuration(voiceIndex?: number): number;
+    /**
+     * Create a Measure from JSON data
+     */
+    static fromJSON(data: MeasureJSON): Measure;
+    transpose(semitones: number): Measure;
+    replaceNote(noteIndex: number, newNote: Note, voiceIndex?: number): Measure;
+    deleteNote(noteIndex: number, voiceIndex?: number): Measure;
+    /**
+     * Automatically update beaming based on time signature
+     */
+    autoBeam(timeSign: TimeSignature): Measure;
+    withTimeSignature(timeSignature?: TimeSignature): Measure;
+    withKeySignature(keySignature?: KeySignature): Measure;
+    withClef(clef?: Clef): Measure;
+    withTempo(tempo?: Tempo): Measure;
+    withSystemBreak(systemBreak: boolean): Measure;
+    withPageBreak(pageBreak: boolean): Measure;
+    withVoices(voices: Note[][]): Measure;
+    withRepeat(repeat?: Repeat): Measure;
+    withRepeats(repeats: Repeat[]): Measure;
+    withVolta(volta?: Volta): Measure;
+    withPickup(isPickup: boolean): Measure;
+    withRehearsalMark(mark?: string): Measure;
+    withSystemText(text?: string): Measure;
+    /**
+     * Fills a specific voice with rests to match the measure's duration.
+     */
+    fillVoiceWithRests(voiceIndex: number, targetDuration: number): Measure;
+    toJSON(): MeasureJSON;
+}
+/**
+ * JSON interface for serialization
+ */
+export interface MeasureJSON {
+    notes?: NoteJSON[];
+    voices?: NoteJSON[][];
+    timeSignature?: TimeSignature;
+    keySignature?: KeySignature;
+    systemBreak?: boolean;
+    pageBreak?: boolean;
+    repeat?: Repeat;
+    repeats?: Repeat[];
+    volta?: Volta;
+    isPickup?: boolean;
+    clef?: Clef;
+    tempo?: Tempo;
+    rehearsalMark?: string;
+    systemText?: string;
+}

package/dist/models/Note.d.ts

@@ -0,0 +1,122 @@
+import { Duration, Accidental, Articulation, Dynamic, Slur, Tuplet, Hairpin, Glissando, Arpeggio, Ottava, Pedal, Ornament, FretboardDiagram, NoteheadShape, Bowing } from './types';
+import { Pitch } from './Pitch';
+/**
+ * Represents a single note or rest in a measure.
+ */
+export declare class Note {
+    readonly duration: Duration;
+    readonly pitch?: Pitch | undefined;
+    readonly isRest: boolean;
+    readonly isDotted: boolean;
+    readonly accidental?: Accidental | undefined;
+    readonly beamGroup?: number | undefined;
+    readonly articulation?: Articulation | undefined;
+    readonly dynamic?: Dynamic | undefined;
+    readonly tie?: boolean | undefined;
+    readonly slur?: Slur | undefined;
+    readonly tuplet?: Tuplet | undefined;
+    readonly hairpin?: Hairpin | undefined;
+    readonly isGrace: boolean;
+    readonly lyric?: string | undefined;
+    readonly chord?: string | undefined;
+    readonly glissando?: Glissando | undefined;
+    readonly arpeggio?: Arpeggio | undefined;
+    readonly ottava?: Ottava | undefined;
+    readonly pedal?: Pedal | undefined;
+    readonly ornament?: Ornament | undefined;
+    readonly fret?: number | undefined;
+    readonly string?: number | undefined;
+    readonly fretboardDiagram?: FretboardDiagram | undefined;
+    readonly lyrics?: string[] | undefined;
+    readonly staffText?: string | undefined;
+    readonly color?: string | undefined;
+    readonly notehead?: NoteheadShape | undefined;
+    readonly bowing?: Bowing | undefined;
+    readonly fingering?: number | undefined;
+    constructor(duration: Duration, pitch?: Pitch | undefined, // undefined for rests
+    isRest?: boolean, isDotted?: boolean, accidental?: Accidental | undefined, beamGroup?: number | undefined, // Group ID for beamed notes
+    articulation?: Articulation | undefined, dynamic?: Dynamic | undefined, tie?: boolean | undefined, slur?: Slur | undefined, tuplet?: Tuplet | undefined, hairpin?: Hairpin | undefined, isGrace?: boolean, lyric?: string | undefined, chord?: string | undefined, glissando?: Glissando | undefined, arpeggio?: Arpeggio | undefined, ottava?: Ottava | undefined, pedal?: Pedal | undefined, ornament?: Ornament | undefined, fret?: number | undefined, string?: number | undefined, fretboardDiagram?: FretboardDiagram | undefined, lyrics?: string[] | undefined, staffText?: string | undefined, color?: string | undefined, notehead?: NoteheadShape | undefined, bowing?: Bowing | undefined, fingering?: number | undefined);
+    /**
+     * Get the duration value (quarter note = 1)
+     */
+    getDurationValue(): number;
+    /**
+     * Check if this note should be beamed (eighth or shorter)
+     */
+    isBeamable(): boolean;
+    withGrace(isGrace: boolean): Note;
+    withChord(chord?: string): Note;
+    /**
+     * Create a note from JSON data
+     */
+    static fromJSON(data: NoteJSON): Note;
+    transpose(semitones: number): Note;
+    transposeOctave(octaves: number): Note;
+    transposeDiatonic(steps: number): Note;
+    toggleEnharmonic(): Note;
+    withPitch(pitch: Pitch): Note;
+    withArticulation(articulation?: Articulation): Note;
+    withDynamic(dynamic?: Dynamic): Note;
+    withTie(tie?: boolean): Note;
+    withSlur(slur?: Slur): Note;
+    withTuplet(tuplet?: Tuplet): Note;
+    withLyric(lyric?: string): Note;
+    withLyrics(lyrics: string[]): Note;
+    withHairpin(hairpin?: Hairpin): Note;
+    withAccidental(accidental?: Accidental): Note;
+    withDuration(duration: Duration, isDotted?: boolean): Note;
+    withRest(isRest: boolean): Note;
+    withFretboardDiagram(diagram?: FretboardDiagram): Note;
+    withBeamGroup(beamGroup?: number): Note;
+    toJSON(): NoteJSON;
+    withGlissando(glissando?: Glissando): Note;
+    withArpeggio(arpeggio?: Arpeggio): Note;
+    withOttava(ottava?: Ottava): Note;
+    withPedal(pedal?: Pedal): Note;
+    withOrnament(ornament?: Ornament): Note;
+    withTab(fret: number, string: number): Note;
+    withStaffText(text?: string): Note;
+    withColor(color?: string): Note;
+    withNotehead(notehead?: NoteheadShape): Note;
+    withBowing(bowing?: Bowing): Note;
+    withFingering(fingering?: number): Note;
+}
+/**
+ * JSON interface for serialization
+ */
+export interface NoteJSON {
+    duration: string;
+    pitch?: {
+        midiNumber: number;
+        step?: number;
+        alter?: number;
+        octave?: number;
+    };
+    isRest?: boolean;
+    isDotted?: boolean;
+    accidental?: string;
+    beamGroup?: number;
+    articulation?: string;
+    dynamic?: string;
+    tie?: boolean;
+    slur?: Slur;
+    tuplet?: Tuplet;
+    hairpin?: Hairpin;
+    isGrace?: boolean;
+    lyric?: string;
+    chord?: string;
+    glissando?: Glissando;
+    arpeggio?: Arpeggio;
+    ottava?: Ottava;
+    pedal?: Pedal;
+    ornament?: Ornament;
+    fret?: number;
+    string?: number;
+    fretboardDiagram?: FretboardDiagram;
+    lyrics?: string[];
+    staffText?: string;
+    color?: string;
+    notehead?: string;
+    bowing?: string;
+    fingering?: number;
+}

package/dist/models/Part.d.ts

@@ -0,0 +1,60 @@
+import { Staff, StaffJSON } from './Staff';
+import { Instrument } from './Instrument';
+import { Note } from './Note';
+import { Measure } from './Measure';
+import { Duration } from './types';
+/**
+ * Represents a musical part (instrument/voice) which can have multiple staves.
+ * For example, a piano part typically has 2 staves (treble and bass).
+ */
+export declare class Part {
+    readonly name: string;
+    readonly staves: Staff[];
+    readonly abbreviation: string;
+    readonly instrument: Instrument;
+    constructor(name: string, staves: Staff[], abbreviation?: string, instrument?: Instrument);
+    /**
+     * Check if this is a multi-staff part (like piano)
+     */
+    isMultiStaff(): boolean;
+    /**
+     * Get the total number of measures (from the first staff)
+     */
+    getMeasureCount(): number;
+    /**
+     * Create a Part from JSON data
+     */
+    static fromJSON(data: PartJSON): Part;
+    /**
+     * Transpose all staves in this part by semitones
+     */
+    transpose(semitones: number): Part;
+    /**
+     * Replace a note in a specific staff/measure
+     */
+    replaceNote(staffIndex: number, measureIndex: number, noteIndex: number, newNote: Note, voiceIndex?: number): Part;
+    replaceMeasure(staffIndex: number, measureIndex: number, newMeasure: Measure): Part;
+    /**
+     * Delete a note in a specific staff/measure
+     */
+    deleteNote(staffIndex: number, measureIndex: number, noteIndex: number, voiceIndex?: number): Part;
+    /**
+     * Change note duration in a specific staff/measure
+     */
+    changeNoteDuration(staffIndex: number, measureIndex: number, noteIndex: number, newDuration: Duration, isDotted?: boolean, voiceIndex?: number): Part;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): PartJSON;
+    withInstrument(instrument: Instrument): Part;
+    replaceStaff(staffIndex: number, newStaff: Staff): Part;
+    withStaves(staves: Staff[]): Part;
+    addMeasure(index: number, measure: Measure): Part;
+    deleteMeasure(index: number): Part;
+}
+export interface PartJSON {
+    name: string;
+    staves: StaffJSON[];
+    abbreviation?: string;
+    instrument?: Instrument;
+}

package/dist/models/Pitch.d.ts

@@ -0,0 +1,45 @@
+import { Clef } from './types';
+/**
+ * Pitch representation using MIDI numbers and explicit spelling (step, alter, octave).
+ */
+export declare class Pitch {
+    readonly midiNumber: number;
+    readonly step: number;
+    readonly alter: number;
+    readonly octave: number;
+    constructor(midiNumber: number, step?: number, alter?: number, octave?: number);
+    /**
+     * Get the note name (e.g., "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B")
+     * Note: This returns the default name for the midi number, not necessarily the spelled name.
+     */
+    getNoteName(): string;
+    /**
+     * Get the octave number (C4 = octave 4)
+     */
+    getOctave(): number;
+    /**
+     * Get staff position relative to the middle line of the staff.
+     */
+    getStaffPosition(clef: Clef): number;
+    /**
+     * Get absolute diatonic step count (octave * 7 + diatonic step)
+     */
+    getAbsoluteDiatonicStep(): number;
+    /**
+     * Get the diatonic step index (0-based from C).
+     */
+    getDiatonicStep(): number;
+    /**
+     * Move this pitch by a number of diatonic steps (staff lines/spaces).
+     */
+    transposeDiatonic(steps: number): Pitch;
+    /**
+     * Cycle to the next common enharmonic spelling.
+     */
+    withEnharmonicNext(): Pitch;
+    /**
+     * Create a Pitch from note name and octave
+     */
+    static fromNoteName(note: string, octave: number): Pitch;
+    static fromStaffPosition(clef: Clef, staffPosition: number): Pitch;
+}