musicxml-io 0.2.5 → 0.2.8

package/README.md

@@ -13,25 +13,46 @@ TypeScript library for parsing and serializing MusicXML.
 │   .xml / .mxl   │─────▶│      Score      │─────▶│   .xml / .mxl   │
 └─────────────────┘      │                 │      └─────────────────┘
                    parse │   ┌─────────┐   │ serialize
-                         │   │ parts  │    │      ┌─────────────────┐
-                         │   │  └─measures │   　　|     MIDI        │
+                         │   │ parts   │   │      ┌─────────────────┐
+                         │   │  └─measures │      │     MIDI        │
                          │   │    └─entries│─────▶│   .mid          │
                          │   └─────────┘   │      └─────────────────┘
                          │                 │ exportMidi
                          └────────┬────────┘
                                   │
-                    ┌─────────────┼─────────────┐
-                    │             │             │
-                    ▼             ▼             ▼
-              ┌──────────┐ ┌──────────┐ ┌──────────┐
-              │ Query    │ │Operations│ │ Validate │
-              │          │ │          │ │          │
-              │findNotes │ │transpose │ │validate  │
-              │getMeasure│ │addNote   │ │isValid   │
-              │countNotes│ │changeKey │ │assertValid
-              └──────────┘ └──────────┘ └──────────┘
+              ┌───────────────────┼───────────────────┐
+              │                   │                   │
+              ▼                   ▼                   ▼
+     ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+     │ QUERIES         │ │ OPERATIONS      │ │ ACCESSORS       │
+     │                 │ │                 │ │                 │
+     │ Score-level     │ │ Score mutation  │ │ Entry-level     │
+     │ read operations │ │ operations      │ │ helpers         │
+     │                 │ │                 │ │                 │
+     │ getMeasure()    │ │ transpose()     │ │ isRest()        │
+     │ findNotes()     │ │ addNote()       │ │ isPitchedNote() │
+     │ getAllNotes()   │ │ changeKey()     │ │ getPartName()   │
+     │ getHarmonies()  │ │ insertMeasure() │ │ hasTie()        │
+     └─────────────────┘ └─────────────────┘ └─────────────────┘
+                                  │
+                                  ▼
+                         ┌─────────────────┐
+                         │ VALIDATE        │
+                         │                 │
+                         │ validate()      │
+                         │ isValid()       │
+                         │ assertValid()   │
+                         └─────────────────┘
 ```
 
+### Module Structure
+
+| Module | File | Description |
+|--------|------|-------------|
+| Query | `src/query/index.ts` | Score-level read operations (get, find, iterate) |
+| Operations | `src/operations/index.ts` | Score mutation operations (add, delete, modify) |
+| Accessors | `src/entry-accessors.ts` | Entry-level helpers for notes, directions, parts |
+
 ## Install
 
 ```bash
@@ -77,11 +98,49 @@ const waltz = changeTime(score, { beats: 3, beatType: 4 }, 0, 1);
 ### Query
 
 ```typescript
-import { findNotes, getAllNotes, getMeasureCount } from 'musicxml-io';
+import { findNotes, getAllNotes, getMeasureCount, getHarmonies } from 'musicxml-io';
 
 const notes = getAllNotes(score);
-const quarterNotes = findNotes(score, { type: 'quarter' });
-const count = getMeasureCount(score.parts[0]);
+const quarterNotes = findNotes(score, { noteType: 'quarter' });
+const count = getMeasureCount(score);
+const harmonies = getHarmonies(score);  // chord symbols (C7, Dm, etc.)
+```
+
+### Accessors
+
+Entry-level helpers for working with individual notes, directions, and parts:
+
+```typescript
+import {
+  getAllNotes,
+  isRest, isPitchedNote, hasTie, isChordNote,
+  getPartName,
+  getDirectionOfKind, getSoundTempo
+} from 'musicxml-io';
+
+// NoteEntry helpers
+for (const item of getAllNotes(score)) {
+  if (isRest(item.note)) continue;
+  if (isPitchedNote(item.note)) {
+    console.log(`${item.note.pitch!.step}${item.note.pitch!.octave}`);
+  }
+  if (hasTie(item.note)) console.log('Tied note');
+  if (isChordNote(item.note)) console.log('Part of chord');
+}
+
+// PartInfo helpers
+const partName = getPartName(score, 'P1'); // 'Piano'
+
+// DirectionEntry helpers
+for (const entry of measure.entries) {
+  if (entry.type === 'direction') {
+    const dynamics = getDirectionOfKind(entry, 'dynamics');
+    if (dynamics) console.log(dynamics.value); // 'ff', 'pp', etc.
+
+    const tempo = getSoundTempo(entry);
+    if (tempo) console.log(`Tempo: ${tempo} BPM`);
+  }
+}
 ```
 
 ### MIDI Export
@@ -123,8 +182,10 @@ const { valid, errors } = validate(score);
 | `addNote(score, options)` | Add note |
 | `deleteNote(score, options)` | Delete note |
 | `addChordNote(score, options)` | Add to chord |
-| `changeKey(score, key, part, measure)` | Change key |
-| `changeTime(score, time, part, measure)` | Change time |
+| `modifyNotePitch(score, options)` | Change note pitch |
+| `modifyNoteDuration(score, options)` | Change note duration |
+| `changeKey(score, key, part, measure)` | Change key signature |
+| `changeTime(score, time, part, measure)` | Change time signature |
 | `insertMeasure(score, part, after)` | Insert measure |
 | `deleteMeasure(score, part, measure)` | Delete measure |
 
@@ -132,12 +193,62 @@ const { valid, errors } = validate(score);
 
 | Function | Description |
 |----------|-------------|
-| `getAllNotes(score)` | All notes |
-| `findNotes(score, filter)` | Filter notes |
-| `getMeasure(part, number)` | Get measure |
-| `getMeasureCount(part)` | Measure count |
-| `getChords(measure)` | Chord groups |
-| `countNotes(score)` | Notes per part |
+| `getAllNotes(score)` | All notes with context |
+| `findNotes(score, filter)` | Filter notes by criteria |
+| `getMeasure(score, { part, measure })` | Get measure by number |
+| `getMeasureByIndex(score, { part, measureIndex })` | Get measure by index |
+| `getMeasureCount(score)` | Total measure count |
+| `getChords(measure)` | Chord groups in measure |
+| `countNotes(score)` | Total note count |
+| `getHarmonies(score)` | All chord symbols |
+| `getDynamics(score)` | All dynamics markings |
+| `getTempoMarkings(score)` | All tempo markings |
+
+### Accessors
+
+Entry-level helpers for individual notes, directions, and parts.
+
+**NoteEntry**
+
+| Function | Description |
+|----------|-------------|
+| `isRest(note)` | Check if rest |
+| `isPitchedNote(note)` | Check if has pitch |
+| `isUnpitchedNote(note)` | Check if percussion |
+| `isChordNote(note)` | Check if part of chord |
+| `isGraceNote(note)` | Check if grace note |
+| `isCueNote(note)` | Check if cue note |
+| `hasTie(note)` | Check if tied |
+| `hasTieStart(note)` | Check if tie starts |
+| `hasTieStop(note)` | Check if tie stops |
+| `hasBeam(note)` | Check if beamed |
+| `hasLyrics(note)` | Check if has lyrics |
+| `hasNotations(note)` | Check if has notations |
+| `hasTuplet(note)` | Check if in tuplet |
+
+**DirectionEntry**
+
+| Function | Description |
+|----------|-------------|
+| `getDirectionOfKind(entry, kind)` | Get first direction type |
+| `getDirectionsOfKind(entry, kind)` | Get all direction types |
+| `hasDirectionOfKind(entry, kind)` | Check if has type |
+| `getSoundTempo(entry)` | Get tempo from sound |
+| `getSoundDynamics(entry)` | Get dynamics (0-127) |
+| `getSoundDamperPedal(entry)` | Get damper pedal state |
+| `getSoundSoftPedal(entry)` | Get soft pedal state |
+| `getSoundSostenutoPedal(entry)` | Get sostenuto pedal state |
+
+**PartInfo**
+
+| Function | Description |
+|----------|-------------|
+| `getPartInfo(score, id)` | Get part info by ID |
+| `getPartName(score, id)` | Get part name |
+| `getPartAbbreviation(score, id)` | Get part abbreviation |
+| `getAllPartInfos(score)` | Get all part infos |
+| `getPartNameMap(score)` | Get ID to name map |
+| `isPartInfo(entry)` | Type guard for PartInfo |
 
 ### Validate
 
@@ -152,8 +263,36 @@ const { valid, errors } = validate(score);
 ```typescript
 import { transpose } from 'musicxml-io/operations';
 import { findNotes } from 'musicxml-io/query';
+import { isRest, getPartName } from 'musicxml-io/entry-accessors';
 ```
 
+## Unique Element IDs
+
+All elements in the Score structure have a unique `_id` property that is automatically generated when:
+- MusicXML is parsed/imported
+- New elements are created via operations
+
+The ID format is `"i" + nanoid(10)` (11 characters total), where:
+- `"i"` prefix ensures XML ID compatibility (IDs must start with a letter or underscore)
+- `nanoid(10)` generates a URL-safe unique identifier
+
+```typescript
+import { parse, generateId } from 'musicxml-io';
+
+const score = parse(xmlString);
+console.log(score._id);           // e.g., "iV1StGXR8_Z"
+console.log(score.parts[0]._id);  // e.g., "i2x4K9mL1Qp"
+
+// Generate IDs manually for custom elements
+const customId = generateId();    // e.g., "iAb3Cd5Ef7H"
+```
+
+This feature enables:
+- Tracking elements across transformations
+- Building element references in external systems
+- Implementing undo/redo functionality
+- Diffing and merging scores
+
 ## Round-trip Fidelity
 
 | Metric | Score |

package/dist/{index-CJUkJI2P.d.ts → index-B-GcfEfL.d.ts}

@@ -1,4 +1,4 @@
-import { S as Score, M as Measure, n as TimeSignature, e as Part, N as NoteEntry, K as KeySignature, P as Pitch, C as Clef, ad as ArticulationType, m as DynamicsValue, ae as OrnamentType, h as NoteType } from './types-D3LhKCDK.js';
+import { S as Score, M as Measure, n as TimeSignature, f as Part, N as NoteEntry, K as KeySignature, P as Pitch, C as Clef, ac as ArticulationType, m as DynamicsValue, ad as OrnamentType, i as NoteType } from './types-Bpq2o5JS.js';
 
 type ValidationErrorCode = 'MISSING_DIVISIONS' | 'INVALID_DIVISIONS' | 'MEASURE_DURATION_MISMATCH' | 'MEASURE_DURATION_OVERFLOW' | 'MEASURE_DURATION_UNDERFLOW' | 'VOICE_INCOMPLETE' | 'VOICE_GAP' | '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';

package/dist/{index-Hm73jOKD.d.mts → index-BvwdY5YQ.d.mts}

@@ -1,4 +1,4 @@
-import { S as Score, M as Measure, n as TimeSignature, e as Part, N as NoteEntry, K as KeySignature, P as Pitch, C as Clef, ad as ArticulationType, m as DynamicsValue, ae as OrnamentType, h as NoteType } from './types-D3LhKCDK.mjs';
+import { S as Score, M as Measure, n as TimeSignature, f as Part, N as NoteEntry, K as KeySignature, P as Pitch, C as Clef, ac as ArticulationType, m as DynamicsValue, ad as OrnamentType, i as NoteType } from './types-Bpq2o5JS.mjs';
 
 type ValidationErrorCode = 'MISSING_DIVISIONS' | 'INVALID_DIVISIONS' | 'MEASURE_DURATION_MISMATCH' | 'MEASURE_DURATION_OVERFLOW' | 'MEASURE_DURATION_UNDERFLOW' | 'VOICE_INCOMPLETE' | 'VOICE_GAP' | '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';

package/dist/index.d.mts

@@ -1,9 +1,8 @@
-import { S as Score, P as Pitch, M as Measure } from './types-D3LhKCDK.mjs';
-export { A as Accidental, i as AccidentalInfo, O as AdjacentNotes, a4 as AssembledLyrics, B as BackupEntry, p as Barline, a5 as BarlineWithContext, a0 as BeamGroup, j as BeamInfo, s as Chord, C as Clef, aa as ClefChangeInfo, w as Credit, v as Defaults, D as DirectionEntry, Q as DirectionKind, l as DirectionType, z as DirectionWithContext, R as DynamicWithContext, m as DynamicsValue, a7 as EndingInfo, E as EntryWithContext, F as ForwardEntry, a2 as HarmonyWithContext, a8 as KeyChangeInfo, K as KeySignature, L as Lyric, a3 as LyricWithContext, f as MeasureAttributes, g as MeasureEntry, k as Notation, a1 as NotationType, N as NoteEntry, t as NoteIteratorItem, h as NoteType, y as NoteWithContext, r as NoteWithPosition, Y as OctaveShiftWithContext, e as Part, c as PartGroup, b as PartInfo, d as PartListEntry, W as PedalWithContext, H as PositionQueryOptions, u as Print, a6 as RepeatInfo, a as ScoreMetadata, _ as SlurSpan, q as StaffGroup, G as StaffRange, ab as StructuralChanges, U as TempoWithContext, T as TieInfo, Z as TiedNoteGroup, a9 as TimeChangeInfo, n as TimeSignature, o as Transpose, $ as TupletGroup, I as VerticalSlice, V as VoiceGroup, J as VoiceLine, x as VoiceToStaffMap, X as WedgeWithContext } from './types-D3LhKCDK.mjs';
-import { V as ValidateOptions, a as ValidationResult } from './index-Hm73jOKD.mjs';
-export { L as LocalValidateOptions, M as MeasureValidationContext, G as ValidationError, I as ValidationErrorCode, C as ValidationException, J as ValidationLevel, H as ValidationLocation, g as addChordNote, b as addNote, F as assertMeasureValid, k as assertValid, c as changeKey, e as changeTime, f as deleteMeasure, d as deleteNote, B as formatLocation, E as getMeasureContext, i as insertMeasure, j as isValid, h as modifyNoteDuration, m as modifyNotePitch, t as transpose, v as validate, o as validateBackupForward, q as validateBeams, l as validateDivisions, n as validateMeasureDuration, D as validateMeasureLocal, u as validatePartReferences, w as validatePartStructure, r as validateSlurs, A as validateSlursAcrossMeasures, x as validateStaffStructure, p as validateTies, z as validateTiesAcrossMeasures, s as validateTuplets, y as validateVoiceStaff } from './index-Hm73jOKD.mjs';
-export { NormalizedPositionOptions, VoiceFilter, buildVoiceToStaffMap, buildVoiceToStaffMapForPart, findBarlines, findDirectionsByType, findNotesWithNotation, getAbsolutePosition, getAdjacentNotes, getAllNotes, getBeamGroups, getChordProgression, getChords, getClefChanges, getClefForStaff, getDirections, getDirectionsAtPosition, getDynamics, getEffectiveStaff, getEndings, getEntriesAtPosition, getEntriesForStaff, getEntriesInRange, getHarmonies, getHarmonyAtPosition, getKeyChanges, getLyricText, getLyrics, getNextNote, getNormalizedDuration, getNormalizedPosition, getNotesAtPosition, getNotesForStaff, getNotesForVoice, getNotesInRange, getOctaveShifts, getPartByIndex, getPartCount, getPartIds, getPedalMarkings, getPrevNote, getRepeatStructure, getSlurSpans, getStaffRange, getStaves, getStructuralChanges, getTempoMarkings, getTiedNoteGroups, getTimeChanges, getTupletGroups, getVerseCount, getVerticalSlice, getVoiceLine, getVoiceLineInRange, getVoices, getVoicesForStaff, getWedges, groupByStaff, groupByVoice, hasNotes, inferStaff, isRestMeasure, iterateEntries, iterateNotes, withAbsolutePositions } from './accessors/index.mjs';
-export { FindNotesFilter, PitchRange, RoundtripMetrics, countNotes, findNotes, getAttributesAtMeasure, getDivisions, getDuration, getMeasure, getMeasureByIndex, getMeasureCount, getPartById, getPartIndex, getStaveCount, hasMultipleStaves, measureRoundtrip, scoresEqual } from './query/index.mjs';
+import { S as Score, P as Pitch, M as Measure, D as DirectionType, a as DirectionEntry, N as NoteEntry, b as PartListEntry, c as PartInfo } from './types-Bpq2o5JS.mjs';
+export { A as Accidental, j as AccidentalInfo, O as AdjacentNotes, a4 as AssembledLyrics, B as BackupEntry, p as Barline, a5 as BarlineWithContext, a0 as BeamGroup, k as BeamInfo, s as Chord, C as Clef, aa as ClefChangeInfo, w as Credit, v as Defaults, Q as DirectionKind, z as DirectionWithContext, R as DynamicWithContext, m as DynamicsValue, a7 as EndingInfo, E as EntryWithContext, F as ForwardEntry, a2 as HarmonyWithContext, a8 as KeyChangeInfo, K as KeySignature, L as Lyric, a3 as LyricWithContext, g as MeasureAttributes, h as MeasureEntry, l as Notation, a1 as NotationType, t as NoteIteratorItem, i as NoteType, y as NoteWithContext, r as NoteWithPosition, Y as OctaveShiftWithContext, f as Part, e as PartGroup, W as PedalWithContext, H as PositionQueryOptions, u as Print, a6 as RepeatInfo, d as ScoreMetadata, _ as SlurSpan, q as StaffGroup, G as StaffRange, ab as StructuralChanges, U as TempoWithContext, T as TieInfo, Z as TiedNoteGroup, a9 as TimeChangeInfo, n as TimeSignature, o as Transpose, $ as TupletGroup, I as VerticalSlice, V as VoiceGroup, J as VoiceLine, x as VoiceToStaffMap, X as WedgeWithContext } from './types-Bpq2o5JS.mjs';
+import { V as ValidateOptions, a as ValidationResult } from './index-BvwdY5YQ.mjs';
+export { L as LocalValidateOptions, M as MeasureValidationContext, G as ValidationError, I as ValidationErrorCode, C as ValidationException, J as ValidationLevel, H as ValidationLocation, g as addChordNote, b as addNote, F as assertMeasureValid, k as assertValid, c as changeKey, e as changeTime, f as deleteMeasure, d as deleteNote, B as formatLocation, E as getMeasureContext, i as insertMeasure, j as isValid, h as modifyNoteDuration, m as modifyNotePitch, t as transpose, v as validate, o as validateBackupForward, q as validateBeams, l as validateDivisions, n as validateMeasureDuration, D as validateMeasureLocal, u as validatePartReferences, w as validatePartStructure, r as validateSlurs, A as validateSlursAcrossMeasures, x as validateStaffStructure, p as validateTies, z as validateTiesAcrossMeasures, s as validateTuplets, y as validateVoiceStaff } from './index-BvwdY5YQ.mjs';
+export { FindNotesFilter, NormalizedPositionOptions, PitchRange, RoundtripMetrics, VoiceFilter, buildVoiceToStaffMap, buildVoiceToStaffMapForPart, countNotes, findBarlines, findDirectionsByType, findNotes, findNotesWithNotation, getAbsolutePosition, getAdjacentNotes, getAllNotes, getAttributesAtMeasure, getBeamGroups, getChordProgression, getChords, getClefChanges, getClefForStaff, getDirections, getDirectionsAtPosition, getDivisions, getDuration, getDynamics, getEffectiveStaff, getEndings, getEntriesAtPosition, getEntriesForStaff, getEntriesInRange, getHarmonies, getHarmonyAtPosition, getKeyChanges, getLyricText, getLyrics, getMeasure, getMeasureByIndex, getMeasureCount, getNextNote, getNormalizedDuration, getNormalizedPosition, getNotesAtPosition, getNotesForStaff, getNotesForVoice, getNotesInRange, getOctaveShifts, getPartById, getPartByIndex, getPartCount, getPartIds, getPartIndex, getPedalMarkings, getPrevNote, getRepeatStructure, getSlurSpans, getStaffRange, getStaveCount, getStaves, getStructuralChanges, getTempoMarkings, getTiedNoteGroups, getTimeChanges, getTupletGroups, getVerseCount, getVerticalSlice, getVoiceLine, getVoiceLineInRange, getVoices, getVoicesForStaff, getWedges, groupByStaff, groupByVoice, hasMultipleStaves, hasNotes, inferStaff, isRestMeasure, iterateEntries, iterateNotes, measureRoundtrip, scoresEqual, withAbsolutePositions } from './query/index.mjs';
 
 declare function parse(xmlString: string): Score;
 
@@ -104,4 +103,199 @@ declare function pitchToSemitone(pitch: Pitch): number;
 /** Get position at end of measure */
 declare function getMeasureEndPosition(measure: Measure): number;
 
-export { Measure, type MidiExportOptions, Pitch, STEPS, STEP_SEMITONES, Score, type SerializeOptions, ValidateOptions, ValidationResult, decodeBuffer, exportMidi, getMeasureEndPosition, isCompressed, parse, parseAuto, parseCompressed, parseFile, pitchToSemitone, serialize, serializeCompressed, serializeToFile };
+/**
+ * Entry-level accessors for DirectionEntry, NoteEntry, and PartInfo
+ *
+ * These are simple helper functions for working with individual entries,
+ * complementing the score-level query functions in ./query.
+ */
+
+/**
+ * Extracts a specific DirectionType union member by its kind
+ */
+type DirectionTypeOfKind<K extends DirectionType['kind']> = Extract<DirectionType, {
+    kind: K;
+}>;
+/**
+ * Get the first direction type of a specific kind from a DirectionEntry
+ *
+ * @example
+ * const dynamics = getDirectionOfKind(entry, 'dynamics');
+ * if (dynamics) {
+ *   console.log(dynamics.value); // 'ff', 'pp', etc.
+ * }
+ */
+declare function getDirectionOfKind<K extends DirectionType['kind']>(entry: DirectionEntry, kind: K): DirectionTypeOfKind<K> | undefined;
+/**
+ * Get all direction types of a specific kind from a DirectionEntry
+ *
+ * @example
+ * const allWords = getDirectionsOfKind(entry, 'words');
+ * allWords.forEach(w => console.log(w.text));
+ */
+declare function getDirectionsOfKind<K extends DirectionType['kind']>(entry: DirectionEntry, kind: K): DirectionTypeOfKind<K>[];
+/**
+ * Check if a DirectionEntry contains a specific direction type
+ *
+ * @example
+ * if (hasDirectionOfKind(entry, 'metronome')) {
+ *   // Handle tempo marking
+ * }
+ */
+declare function hasDirectionOfKind(entry: DirectionEntry, kind: DirectionType['kind']): boolean;
+/**
+ * Get tempo from DirectionEntry.sound
+ *
+ * @example
+ * const tempo = getSoundTempo(entry); // 120
+ */
+declare function getSoundTempo(entry: DirectionEntry): number | undefined;
+/**
+ * Get dynamics value from DirectionEntry.sound (MIDI velocity 0-127)
+ *
+ * @example
+ * const dynamics = getSoundDynamics(entry); // 80
+ */
+declare function getSoundDynamics(entry: DirectionEntry): number | undefined;
+/**
+ * Get damper pedal state from DirectionEntry.sound
+ */
+declare function getSoundDamperPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Get soft pedal state from DirectionEntry.sound
+ */
+declare function getSoundSoftPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Get sostenuto pedal state from DirectionEntry.sound
+ */
+declare function getSoundSostenutoPedal(entry: DirectionEntry): 'yes' | 'no' | undefined;
+/**
+ * Check if a NoteEntry is a rest
+ *
+ * @example
+ * if (isRest(note)) {
+ *   console.log('This is a rest');
+ * }
+ */
+declare function isRest(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a pitched note (has pitch information)
+ *
+ * @example
+ * if (isPitchedNote(note)) {
+ *   console.log(`Note: ${note.pitch!.step}${note.pitch!.octave}`);
+ * }
+ */
+declare function isPitchedNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is an unpitched note (percussion)
+ */
+declare function isUnpitchedNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is part of a chord (shares onset with previous note)
+ *
+ * @example
+ * const chordNotes = notes.filter(isChordNote);
+ */
+declare function isChordNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a grace note
+ *
+ * @example
+ * if (isGraceNote(note)) {
+ *   console.log('Grace note with slash:', note.grace?.slash);
+ * }
+ */
+declare function isGraceNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any tie (start, stop, or continue)
+ *
+ * @example
+ * if (hasTie(note)) {
+ *   // Note is tied to another note
+ * }
+ */
+declare function hasTie(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has a tie start
+ */
+declare function hasTieStart(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has a tie stop
+ */
+declare function hasTieStop(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is a cue note
+ */
+declare function isCueNote(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any beams
+ */
+declare function hasBeam(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any lyrics
+ */
+declare function hasLyrics(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry has any notations (articulations, slurs, ornaments, etc.)
+ */
+declare function hasNotations(entry: NoteEntry): boolean;
+/**
+ * Check if a NoteEntry is part of a tuplet
+ */
+declare function hasTuplet(entry: NoteEntry): boolean;
+/**
+ * Check if a PartListEntry is a PartInfo (score-part)
+ */
+declare function isPartInfo(entry: PartListEntry): entry is PartInfo;
+/**
+ * Get PartInfo by part ID
+ *
+ * @example
+ * const partInfo = getPartInfo(score, 'P1');
+ * if (partInfo) {
+ *   console.log(partInfo.name); // 'Piano'
+ * }
+ */
+declare function getPartInfo(score: Score, partId: string): PartInfo | undefined;
+/**
+ * Get part name by part ID
+ *
+ * @example
+ * const name = getPartName(score, 'P1'); // 'Piano'
+ */
+declare function getPartName(score: Score, partId: string): string | undefined;
+/**
+ * Get part abbreviation by part ID
+ *
+ * @example
+ * const abbr = getPartAbbreviation(score, 'P1'); // 'Pno.'
+ */
+declare function getPartAbbreviation(score: Score, partId: string): string | undefined;
+/**
+ * Get all PartInfo entries from a score
+ */
+declare function getAllPartInfos(score: Score): PartInfo[];
+/**
+ * Get a map of part ID to part name
+ *
+ * @example
+ * const names = getPartNameMap(score);
+ * // { 'P1': 'Piano', 'P2': 'Violin' }
+ */
+declare function getPartNameMap(score: Score): Record<string, string | undefined>;
+
+/**
+ * Generates a unique ID for elements in the Score structure.
+ *
+ * The ID format is "i" + nanoid(10), where:
+ * - "i" prefix ensures XML ID compatibility (XML IDs must start with a letter or underscore)
+ * - nanoid(10) generates a 10-character URL-safe unique identifier
+ *
+ * Example: "iV1StGXR8_"
+ *
+ * @returns A unique 11-character ID string
+ */
+declare function generateId(): string;
+
+export { DirectionEntry, DirectionType, type DirectionTypeOfKind, Measure, type MidiExportOptions, NoteEntry, PartInfo, PartListEntry, Pitch, STEPS, STEP_SEMITONES, Score, type SerializeOptions, ValidateOptions, ValidationResult, decodeBuffer, exportMidi, generateId, getAllPartInfos, getDirectionOfKind, getDirectionsOfKind, getMeasureEndPosition, getPartAbbreviation, getPartInfo, getPartName, getPartNameMap, getSoundDamperPedal, getSoundDynamics, getSoundSoftPedal, getSoundSostenutoPedal, getSoundTempo, hasBeam, hasDirectionOfKind, hasLyrics, hasNotations, hasTie, hasTieStart, hasTieStop, hasTuplet, isChordNote, isCompressed, isCueNote, isGraceNote, isPartInfo, isPitchedNote, isRest, isUnpitchedNote, parse, parseAuto, parseCompressed, parseFile, pitchToSemitone, serialize, serializeCompressed, serializeToFile };