musicxml-io 0.2.7 → 0.2.9

package/dist/query/index.d.mts

@@ -1,5 +1,361 @@
-import { S as Score, M as Measure, f as MeasureAttributes, P as Pitch, N as NoteEntry, e as Part } from '../types-CSI8kV28.mjs';
+import { M as Measure, N as NoteEntry, V as VoiceGroup, q as StaffGroup, r as NoteWithPosition, s as Chord, S as Score, t as NoteIteratorItem, h as MeasureEntry, x as VoiceToStaffMap, f as Part, C as Clef, G as StaffRange, H as PositionQueryOptions, I as VerticalSlice, J as VoiceLine, E as EntryWithContext, y as NoteWithContext, O as AdjacentNotes, z as DirectionWithContext, a as DirectionEntry, Q as DirectionKind, R as DynamicWithContext, U as TempoWithContext, W as PedalWithContext, X as WedgeWithContext, Y as OctaveShiftWithContext, Z as TiedNoteGroup, _ as SlurSpan, $ as TupletGroup, a0 as BeamGroup, a1 as NotationType, a2 as HarmonyWithContext, ae as HarmonyEntry, a3 as LyricWithContext, a4 as AssembledLyrics, a6 as RepeatInfo, a5 as BarlineWithContext, a7 as EndingInfo, a8 as KeyChangeInfo, a9 as TimeChangeInfo, aa as ClefChangeInfo, ab as StructuralChanges, g as MeasureAttributes, P as Pitch } from '../types-Bpq2o5JS.mjs';
 
+/**
+ * Filter options for voice/staff selection
+ */
+interface VoiceFilter {
+    voice?: number;
+    staff?: number;
+}
+/**
+ * Get all notes for a specific voice (and optionally staff)
+ */
+declare function getNotesForVoice(measure: Measure, filter: VoiceFilter): NoteEntry[];
+/**
+ * Get all notes for a specific staff (regardless of voice)
+ */
+declare function getNotesForStaff(measure: Measure, filter: {
+    staff: number;
+}): NoteEntry[];
+/**
+ * Group notes by voice (and staff)
+ */
+declare function groupByVoice(measure: Measure): VoiceGroup[];
+/**
+ * Group notes by staff
+ */
+declare function groupByStaff(measure: Measure): StaffGroup[];
+/**
+ * Calculate absolute position of a note within a measure
+ * Position is in divisions from the start of the measure
+ */
+declare function getAbsolutePosition(note: NoteEntry, measure: Measure): number;
+/**
+ * Add absolute position to all notes in a measure
+ */
+declare function withAbsolutePositions(measure: Measure): NoteWithPosition[];
+/**
+ * Get chords (groups of simultaneously sounding notes)
+ */
+declare function getChords(measure: Measure, filter?: VoiceFilter): Chord[];
+/**
+ * Iterate over all notes in a score
+ */
+declare function iterateNotes(score: Score): Generator<NoteIteratorItem>;
+/**
+ * Get all notes from a score as an array
+ */
+declare function getAllNotes(score: Score): NoteIteratorItem[];
+/**
+ * Get unique voices used in a measure
+ */
+declare function getVoices(measure: Measure): number[];
+/**
+ * Get unique staves used in a measure
+ */
+declare function getStaves(measure: Measure): number[];
+/**
+ * Check if a measure contains any notes
+ */
+declare function hasNotes(measure: Measure): boolean;
+/**
+ * Check if a measure is a rest (no pitched notes)
+ */
+declare function isRestMeasure(measure: Measure): boolean;
+/**
+ * Options for normalized position calculation
+ */
+interface NormalizedPositionOptions {
+    baseDivisions: number;
+    currentDivisions?: number;
+}
+/**
+ * Get a normalized position of a note using a common base divisions
+ * This is useful when comparing positions across measures with different divisions
+ */
+declare function getNormalizedPosition(note: NoteEntry, measure: Measure, options: NormalizedPositionOptions): number;
+/**
+ * Get normalized duration of a note using a common base divisions
+ */
+declare function getNormalizedDuration(note: NoteEntry, options: NormalizedPositionOptions): number;
+/**
+ * Get all entries for a specific staff (including notes, directions, etc.)
+ */
+declare function getEntriesForStaff(measure: Measure, staff: number): MeasureEntry[];
+/**
+ * Build a Voice to Staff mapping from a measure
+ * Uses explicitly specified staff values to infer staff for voices
+ */
+declare function buildVoiceToStaffMap(measure: Measure): VoiceToStaffMap;
+/**
+ * Build a Voice to Staff mapping from all measures in a part
+ */
+declare function buildVoiceToStaffMapForPart(part: Part): VoiceToStaffMap;
+/**
+ * Infer staff number for an entry using voice-to-staff mapping
+ * Returns 1 as default if unable to infer (per MusicXML spec)
+ */
+declare function inferStaff(entry: NoteEntry, voiceToStaffMap: VoiceToStaffMap): number;
+/**
+ * Get effective staff for an entry (explicit or inferred)
+ */
+declare function getEffectiveStaff(entry: NoteEntry, measure: Measure): number;
+/**
+ * Get the clef for a specific staff at a given measure
+ * Searches backwards from the specified measure to find the most recent clef
+ */
+declare function getClefForStaff(score: Score, options: {
+    partIndex: number;
+    measureIndex: number;
+    staff: number;
+}): Clef | undefined;
+/**
+ * Get all voices used within a specific staff
+ */
+declare function getVoicesForStaff(measure: Measure, staff: number): number[];
+/**
+ * Get the range of staff numbers used in a part
+ */
+declare function getStaffRange(score: Score, partIndex: number): StaffRange;
+/**
+ * Get all entries at a specific position in a measure
+ */
+declare function getEntriesAtPosition(measure: Measure, position: number, options?: PositionQueryOptions): MeasureEntry[];
+/**
+ * Get all notes at a specific position in a measure
+ */
+declare function getNotesAtPosition(measure: Measure, position: number, options?: PositionQueryOptions): NoteEntry[];
+/**
+ * Get all entries within a position range
+ */
+declare function getEntriesInRange(measure: Measure, range: {
+    start: number;
+    end: number;
+}, options?: PositionQueryOptions): MeasureEntry[];
+/**
+ * Get all notes within a position range
+ */
+declare function getNotesInRange(measure: Measure, range: {
+    start: number;
+    end: number;
+}, options?: PositionQueryOptions): NoteEntry[];
+/**
+ * Get a vertical slice of all notes at a specific position across all parts
+ */
+declare function getVerticalSlice(score: Score, options: {
+    measureIndex: number;
+    position: number;
+}): VerticalSlice;
+/**
+ * Get a continuous voice line across all measures
+ */
+declare function getVoiceLine(score: Score, options: {
+    partIndex: number;
+    voice: number;
+    staff?: number;
+}): VoiceLine;
+/**
+ * Get a voice line within a measure range
+ */
+declare function getVoiceLineInRange(score: Score, options: {
+    partIndex: number;
+    voice: number;
+    startMeasure: number;
+    endMeasure: number;
+    staff?: number;
+}): VoiceLine;
+/**
+ * Iterate over all entries in a score (not just notes)
+ */
+declare function iterateEntries(score: Score): Generator<EntryWithContext>;
+/**
+ * Get the next note in the same voice
+ */
+declare function getNextNote(score: Score, context: NoteWithContext): NoteWithContext | null;
+/**
+ * Get the previous note in the same voice
+ */
+declare function getPrevNote(score: Score, context: NoteWithContext): NoteWithContext | null;
+/**
+ * Get both previous and next notes
+ */
+declare function getAdjacentNotes(score: Score, context: NoteWithContext): AdjacentNotes;
+/**
+ * Get all directions from a score or specific part/measure
+ */
+declare function getDirections(score: Score, options?: {
+    partIndex?: number;
+    measureIndex?: number;
+}): DirectionWithContext[];
+/**
+ * Get directions at a specific position in a measure
+ */
+declare function getDirectionsAtPosition(measure: Measure, position: number): DirectionEntry[];
+/**
+ * Find directions by type (kind)
+ */
+declare function findDirectionsByType(score: Score, kind: DirectionKind): DirectionWithContext[];
+/**
+ * Get all dynamics markings from a score
+ */
+declare function getDynamics(score: Score, options?: {
+    partIndex?: number;
+}): DynamicWithContext[];
+/**
+ * Get all tempo markings from a score
+ */
+declare function getTempoMarkings(score: Score): TempoWithContext[];
+/**
+ * Get all pedal markings from a score
+ */
+declare function getPedalMarkings(score: Score, options?: {
+    partIndex?: number;
+}): PedalWithContext[];
+/**
+ * Get all wedges (crescendo/diminuendo) from a score
+ */
+declare function getWedges(score: Score, options?: {
+    partIndex?: number;
+}): WedgeWithContext[];
+/**
+ * Get all octave shifts from a score
+ */
+declare function getOctaveShifts(score: Score, options?: {
+    partIndex?: number;
+}): OctaveShiftWithContext[];
+/**
+ * Get all groups of tied notes in a score
+ * Each group represents notes connected by ties
+ */
+declare function getTiedNoteGroups(score: Score, options?: {
+    partIndex?: number;
+}): TiedNoteGroup[];
+/**
+ * Get all slur spans in a score
+ * Each span represents a slur from start to stop
+ */
+declare function getSlurSpans(score: Score, options?: {
+    partIndex?: number;
+}): SlurSpan[];
+/**
+ * Get all tuplet groups in a score
+ */
+declare function getTupletGroups(score: Score, options?: {
+    partIndex?: number;
+}): TupletGroup[];
+/**
+ * Get all beam groups in a measure
+ * Returns groups of notes connected by beams
+ */
+declare function getBeamGroups(measure: Measure): BeamGroup[];
+/**
+ * Find all notes with a specific notation type
+ */
+declare function findNotesWithNotation(score: Score, notationType: NotationType, options?: {
+    partIndex?: number;
+}): NoteWithContext[];
+/**
+ * Get all harmonies from a score
+ */
+declare function getHarmonies(score: Score, options?: {
+    partIndex?: number;
+}): HarmonyWithContext[];
+/**
+ * Get harmony at a specific position in a measure
+ */
+declare function getHarmonyAtPosition(measure: Measure, position: number): HarmonyEntry | undefined;
+/**
+ * Get chord progression (all harmonies in order)
+ * Returns a simplified representation of the chord progression
+ */
+declare function getChordProgression(score: Score, options?: {
+    partIndex?: number;
+}): {
+    root: string;
+    kind: string;
+    bass?: string;
+    measureIndex: number;
+    position: number;
+}[];
+/**
+ * Get all lyrics from a score
+ */
+declare function getLyrics(score: Score, options?: {
+    partIndex?: number;
+    verse?: number;
+}): LyricWithContext[];
+/**
+ * Get assembled lyric text for a specific verse
+ * Joins syllables with proper hyphenation
+ */
+declare function getLyricText(score: Score, options?: {
+    partIndex?: number;
+    verse?: number;
+}): AssembledLyrics[];
+/**
+ * Get the number of verses in a score
+ */
+declare function getVerseCount(score: Score, options?: {
+    partIndex?: number;
+}): number;
+/**
+ * Get repeat structure from a score
+ * Returns forward and backward repeat markers
+ */
+declare function getRepeatStructure(score: Score, options?: {
+    partIndex?: number;
+}): RepeatInfo[];
+/**
+ * Find barlines matching criteria
+ */
+declare function findBarlines(score: Score, options?: {
+    partIndex?: number;
+    style?: string;
+    repeat?: boolean;
+}): BarlineWithContext[];
+/**
+ * Get all endings (volta brackets) from a score
+ */
+declare function getEndings(score: Score, options?: {
+    partIndex?: number;
+}): EndingInfo[];
+/**
+ * Get all key signature changes in a score
+ */
+declare function getKeyChanges(score: Score, options?: {
+    partIndex?: number;
+}): KeyChangeInfo[];
+/**
+ * Get all time signature changes in a score
+ */
+declare function getTimeChanges(score: Score, options?: {
+    partIndex?: number;
+}): TimeChangeInfo[];
+/**
+ * Get all clef changes in a score
+ */
+declare function getClefChanges(score: Score, options?: {
+    partIndex?: number;
+    staff?: number;
+}): ClefChangeInfo[];
+/**
+ * Get all structural changes in a score (key, time, clef)
+ */
+declare function getStructuralChanges(score: Score, options?: {
+    partIndex?: number;
+}): StructuralChanges;
+/**
+ * Get a part by index
+ */
+declare function getPartByIndex(score: Score, index: number): Part | undefined;
+/**
+ * Get the number of parts in a score
+ */
+declare function getPartCount(score: Score): number;
+/**
+ * Get all part IDs from a score
+ */
+declare function getPartIds(score: Score): string[];
 /**
  * Get a specific measure from the score
  */
@@ -100,4 +456,4 @@ declare function countNotes(score: Score): number;
  */
 declare function scoresEqual(a: Score, b: Score): boolean;
 
-export { type FindNotesFilter, type PitchRange, type RoundtripMetrics, countNotes, findNotes, getAttributesAtMeasure, getDivisions, getDuration, getMeasure, getMeasureByIndex, getMeasureCount, getPartById, getPartIndex, getStaveCount, hasMultipleStaves, measureRoundtrip, scoresEqual };
+export { type FindNotesFilter, type NormalizedPositionOptions, type PitchRange, type RoundtripMetrics, type 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 };