musicxml-io 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,285 @@
+import { S as Score, M as Measure, T as TimeSignature, P as Part, a as Pitch } from './types-DC_TnJu_.js';
+export { A as Accidental, i as AccidentalInfo, B as BackupEntry, p as Barline, k as BeamInfo, s as Chord, C as Clef, w as Credit, v as Defaults, D as DirectionEntry, m as DirectionType, n as DynamicsValue, F as ForwardEntry, K as KeySignature, L as Lyric, f as MeasureAttributes, g as MeasureEntry, l as Notation, N as NoteEntry, t as NoteIteratorItem, h as NoteType, r as NoteWithPosition, d as PartGroup, c as PartInfo, e as PartListEntry, u as Print, b as ScoreMetadata, q as StaffGroup, j as TieInfo, o as Transpose, V as VoiceGroup } from './types-DC_TnJu_.js';
+export { NormalizedPositionOptions, VoiceFilter, getAbsolutePosition, getAllNotes, getChords, getNormalizedDuration, getNormalizedPosition, getNotesForStaff, getNotesForVoice, getStaves, getVoices, groupByStaff, groupByVoice, hasNotes, isRestMeasure, iterateNotes, withAbsolutePositions } from './accessors/index.js';
+export { FindNotesFilter, PitchRange, RoundtripMetrics, countNotes, findNotes, getAttributesAtMeasure, getDivisions, getDuration, getMeasure, getMeasureByIndex, getMeasureCount, getPartById, getPartIndex, getStaveCount, hasMultipleStaves, measureRoundtrip, scoresEqual } from './query/index.js';
+export { AddNoteOptions, addChordNote, addNote, changeKey, changeTime, deleteMeasure, deleteNote, insertMeasure, modifyNoteDuration, modifyNotePitch, setDivisions, transpose } from './operations/index.js';
+
+declare function parse(xmlString: string): Score;
+
+/**
+ * Parse a compressed MusicXML (.mxl) file
+ * @param data - The compressed file data as Uint8Array or Buffer
+ * @returns The parsed Score
+ */
+declare function parseCompressed(data: Uint8Array): Score;
+/**
+ * Check if data is a compressed MusicXML file
+ * @param data - The file data
+ * @returns true if the data appears to be a ZIP file
+ */
+declare function isCompressed(data: Uint8Array): boolean;
+/**
+ * Parse either compressed (.mxl) or uncompressed (.xml/.musicxml) MusicXML
+ * Automatically detects the format
+ * @param data - The file data as Uint8Array or string
+ * @returns The parsed Score
+ */
+declare function parseAuto(data: Uint8Array | string): Score;
+
+type ValidationErrorCode = 'MISSING_DIVISIONS' | 'INVALID_DIVISIONS' | 'MEASURE_DURATION_MISMATCH' | 'MEASURE_DURATION_OVERFLOW' | 'MEASURE_DURATION_UNDERFLOW' | 'NEGATIVE_POSITION' | 'BACKUP_EXCEEDS_POSITION' | 'TIE_START_WITHOUT_STOP' | 'TIE_STOP_WITHOUT_START' | 'TIE_PITCH_MISMATCH' | 'BEAM_BEGIN_WITHOUT_END' | 'BEAM_END_WITHOUT_BEGIN' | 'SLUR_START_WITHOUT_STOP' | 'SLUR_STOP_WITHOUT_START' | 'TUPLET_START_WITHOUT_STOP' | 'TUPLET_STOP_WITHOUT_START' | 'PART_ID_NOT_IN_PART_LIST' | 'PART_LIST_ID_NOT_IN_PARTS' | 'PART_MEASURE_COUNT_MISMATCH' | 'PART_MEASURE_NUMBER_MISMATCH' | 'PART_GROUP_START_WITHOUT_STOP' | 'PART_GROUP_STOP_WITHOUT_START' | 'DUPLICATE_PART_ID' | 'INVALID_VOICE_NUMBER' | 'INVALID_STAFF_NUMBER' | 'STAFF_EXCEEDS_STAVES' | 'MISSING_STAVES_DECLARATION' | 'STAVES_DECLARATION_MISMATCH' | 'MISSING_CLEF_FOR_STAFF' | 'CLEF_STAFF_EXCEEDS_STAVES' | 'INVALID_DURATION' | 'EMPTY_MEASURE';
+type ValidationLevel = 'error' | 'warning' | 'info';
+interface ValidationLocation {
+    partIndex?: number;
+    partId?: string;
+    measureIndex?: number;
+    measureNumber?: string;
+    entryIndex?: number;
+    voice?: number;
+    staff?: number;
+}
+interface ValidationError {
+    code: ValidationErrorCode;
+    level: ValidationLevel;
+    message: string;
+    location: ValidationLocation;
+    details?: Record<string, unknown>;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    infos: ValidationError[];
+}
+interface ValidateOptions {
+    /** Check divisions consistency (default: true) */
+    checkDivisions?: boolean;
+    /** Check measure durations match time signature (default: true) */
+    checkMeasureDuration?: boolean;
+    /** Check backup/forward position consistency (default: true) */
+    checkPosition?: boolean;
+    /** Check tie start/stop pairing (default: true) */
+    checkTies?: boolean;
+    /** Check beam begin/end pairing (default: true) */
+    checkBeams?: boolean;
+    /** Check slur start/stop pairing (default: true) */
+    checkSlurs?: boolean;
+    /** Check tuplet start/stop pairing (default: true) */
+    checkTuplets?: boolean;
+    /** Check part ID references (default: true) */
+    checkPartReferences?: boolean;
+    /** Check part structure (measure count, numbers) (default: true) */
+    checkPartStructure?: boolean;
+    /** Check voice/staff numbers (default: true) */
+    checkVoiceStaff?: boolean;
+    /** Check staff structure (staves declaration, clefs) (default: true) */
+    checkStaffStructure?: boolean;
+    /** Tolerance for measure duration (in divisions, default: 0) */
+    durationTolerance?: number;
+}
+/**
+ * Validate a Score for internal consistency
+ */
+declare function validate(score: Score, options?: ValidateOptions): ValidationResult;
+/**
+ * Validate that divisions are defined and consistent
+ */
+declare function validateDivisions(score: Score): ValidationError[];
+/**
+ * Validate measure duration matches time signature
+ */
+declare function validateMeasureDuration(measure: Measure, divisions: number, time: TimeSignature, location: ValidationLocation, tolerance?: number): ValidationError[];
+/**
+ * Validate backup/forward position consistency
+ */
+declare function validateBackupForward(measure: Measure, location: ValidationLocation): ValidationError[];
+/**
+ * Validate tie start/stop pairing
+ */
+declare function validateTies(measure: Measure, location: ValidationLocation): ValidationError[];
+/**
+ * Validate beam begin/end pairing
+ */
+declare function validateBeams(measure: Measure, location: ValidationLocation): ValidationError[];
+/**
+ * Validate slur start/stop pairing
+ */
+declare function validateSlurs(measure: Measure, _location: ValidationLocation): ValidationError[];
+/**
+ * Validate tuplet start/stop pairing
+ */
+declare function validateTuplets(measure: Measure, location: ValidationLocation): ValidationError[];
+/**
+ * Validate part ID references between partList and parts
+ */
+declare function validatePartReferences(score: Score): ValidationError[];
+/**
+ * Validate voice and staff numbers
+ */
+declare function validateVoiceStaff(measure: Measure, staves: number, location: ValidationLocation): ValidationError[];
+/**
+ * Validate part structure (measure counts and numbers match across parts)
+ */
+declare function validatePartStructure(score: Score): ValidationError[];
+/**
+ * Validate staff structure within a part
+ */
+declare function validateStaffStructure(part: Part, partIndex: number): ValidationError[];
+/**
+ * Context needed to validate a single measure
+ */
+interface MeasureValidationContext {
+    /** Current divisions value (from previous attributes) */
+    divisions: number;
+    /** Current time signature */
+    time?: TimeSignature;
+    /** Current staves count */
+    staves: number;
+    /** Part index (for error location) */
+    partIndex: number;
+    /** Part ID (for error location) */
+    partId: string;
+    /** Measure index (for error location) */
+    measureIndex: number;
+}
+/**
+ * Options for local measure validation
+ */
+interface LocalValidateOptions {
+    checkMeasureDuration?: boolean;
+    checkPosition?: boolean;
+    checkBeams?: boolean;
+    checkTuplets?: boolean;
+    checkVoiceStaff?: boolean;
+    durationTolerance?: number;
+}
+/**
+ * Validate a single measure with provided context.
+ * This is useful for validating after local operations like addNote, deleteNote.
+ *
+ * @example
+ * ```typescript
+ * const context = getMeasureContext(score, partIndex, measureIndex);
+ * const errors = validateMeasureLocal(measure, context);
+ * if (errors.length > 0) {
+ *   throw new Error('Operation created invalid state');
+ * }
+ * ```
+ */
+declare function validateMeasureLocal(measure: Measure, context: MeasureValidationContext, options?: LocalValidateOptions): ValidationError[];
+/**
+ * Get the validation context for a measure by traversing previous attributes.
+ * This collects divisions, time, and staves from measure 0 to the target measure.
+ */
+declare function getMeasureContext(score: Score, partIndex: number, measureIndex: number): MeasureValidationContext;
+/**
+ * Validate a measure after an operation, throwing if invalid.
+ * Convenience wrapper around validateMeasureLocal.
+ */
+declare function assertMeasureValid(score: Score, partIndex: number, measureIndex: number, options?: LocalValidateOptions): void;
+/**
+ * Check if a score is valid (no errors)
+ */
+declare function isValid(score: Score, options?: ValidateOptions): boolean;
+/**
+ * Validate and throw if invalid
+ */
+declare function assertValid(score: Score, options?: ValidateOptions): void;
+/**
+ * Format a validation location for display
+ */
+declare function formatLocation(location: ValidationLocation): string;
+/**
+ * Validation exception with structured error information
+ */
+declare class ValidationException extends Error {
+    readonly errors: ValidationError[];
+    constructor(errors: ValidationError[], message: string);
+}
+/**
+ * Validate ties across measures
+ * This is more complex as ties can span multiple measures
+ */
+declare function validateTiesAcrossMeasures(part: Part): ValidationError[];
+/**
+ * Validate slurs across measures
+ */
+declare function validateSlursAcrossMeasures(part: Part): ValidationError[];
+
+interface SerializeOptions {
+    version?: '3.1' | '4.0';
+    indent?: string;
+    /** Validate score before serializing (default: false) */
+    validate?: boolean;
+    /** Options for validation (if validate is true) */
+    validateOptions?: ValidateOptions;
+    /** Throw error if validation fails (default: false, will only warn) */
+    throwOnValidationError?: boolean;
+    /** Callback to receive validation result */
+    onValidation?: (result: ValidationResult) => void;
+}
+declare function serialize(score: Score, options?: SerializeOptions): string;
+
+/**
+ * Serialize a Score to compressed MusicXML (.mxl) format
+ * @param score - The Score to serialize
+ * @param options - Serialization options
+ * @returns The compressed file data as Uint8Array
+ */
+declare function serializeCompressed(score: Score, options?: SerializeOptions): Uint8Array;
+
+/**
+ * MIDI export options
+ */
+interface MidiExportOptions {
+    /** Ticks per quarter note (default: 480) */
+    ticksPerQuarterNote?: number;
+    /** Default tempo in BPM (default: 120) */
+    defaultTempo?: number;
+    /** Default velocity for notes (default: 80) */
+    defaultVelocity?: number;
+}
+/**
+ * Export a Score to Standard MIDI File format (SMF Type 1)
+ * @param score - The Score to export
+ * @param options - Export options
+ * @returns The MIDI file data as Uint8Array
+ */
+declare function exportMidi(score: Score, options?: MidiExportOptions): Uint8Array;
+
+/**
+ * Parse a MusicXML file from disk
+ * Automatically handles both .xml/.musicxml and .mxl formats
+ * @param filePath - Path to the file
+ * @returns The parsed Score
+ */
+declare function parseFile(filePath: string): Promise<Score>;
+/**
+ * Detect encoding from BOM and decode buffer to string
+ * Supports UTF-8, UTF-16BE, UTF-16LE
+ */
+declare function decodeBuffer(buffer: Buffer): string;
+/**
+ * Export options combining all format options
+ */
+interface ExportOptions extends SerializeOptions, MidiExportOptions {
+}
+/**
+ * Serialize a Score to a file
+ * Format is determined by file extension:
+ * - .mxl: Compressed MusicXML
+ * - .xml/.musicxml: Uncompressed MusicXML
+ * - .mid/.midi: Standard MIDI File
+ * @param score - The Score to serialize
+ * @param filePath - Path to write the file
+ * @param options - Serialization options
+ */
+declare function serializeToFile(score: Score, filePath: string, options?: ExportOptions): Promise<void>;
+
+declare const STEPS: Pitch['step'][];
+declare const STEP_SEMITONES: Record<Pitch['step'], number>;
+/** Convert pitch to semitone value (MIDI-like) */
+declare function pitchToSemitone(pitch: Pitch): number;
+/** Get position at end of measure */
+declare function getMeasureEndPosition(measure: Measure): number;
+
+export { type LocalValidateOptions, Measure, type MeasureValidationContext, type MidiExportOptions, Part, Pitch, STEPS, STEP_SEMITONES, Score, type SerializeOptions, TimeSignature, type ValidateOptions, type ValidationError, type ValidationErrorCode, ValidationException, type ValidationLevel, type ValidationLocation, type ValidationResult, assertMeasureValid, assertValid, decodeBuffer, exportMidi, formatLocation, getMeasureContext, getMeasureEndPosition, isCompressed, isValid, parse, parseAuto, parseCompressed, parseFile, pitchToSemitone, serialize, serializeCompressed, serializeToFile, validate, validateBackupForward, validateBeams, validateDivisions, validateMeasureDuration, validateMeasureLocal, validatePartReferences, validatePartStructure, validateSlurs, validateSlursAcrossMeasures, validateStaffStructure, validateTies, validateTiesAcrossMeasures, validateTuplets, validateVoiceStaff };