mxlimport

Documentation

Overview

Package mxlimport reads MusicXML files — uncompressed .musicxml and the zipped .mxl container — into the score model.

The supported subset is MusicXML 4.0 score-partwise, with MuseScore's exported files as the compatibility target (real MuseScore exports are the validation gap until users supply them; the committed fixtures are hand-authored in MuseScore's flavor). The sound-versus-display dualism is resolved toward sound throughout: <duration> is authoritative for timing (so <type>, <dot/>, and <time-modification> need no separate handling — the duration already reflects them), <tie> (sound) rather than <tied> (notation) drives tie merging, and <sound tempo> wins over <metronome> when a direction carries both.

Subset boundaries, stated plainly:

• Only voice 1 and staff 1 are imported; notes in other voices or staves are skipped with a warning (their durations still move the time cursor, so voice-1 timing is unaffected).
• Grace notes and ornaments are skipped with a warning.
• <backup> and <forward> are honored exactly — mishandling them is the documented silent-corruption trap in partial MusicXML implementations (docs/DECISIONS.md D3), so the cursor math is covered by regression tests.
• <staff-tuning> (line 1 = the LOWEST string on the staff) and <capo> map to the track's Tuning and Capo. <technical><string>/<fret> (string 1 = the HIGHEST-pitched string, the same convention as the score model) are used directly when present; notes without them get an inferred fingering from internal/fretting, marked Inferred.
• Everything else unsupported degrades to a warning, never an error; underfull measures are padded with rests. The result always passes score.Validate.

Ticks are rescaled from the file's <divisions> to score.PPQ. Notes that cross beat or bar boundaries continue as Tied notes, which score.Events merges back into single events — the same round-trip invariant as internal/midiimport.

Index

• Constants
• func Import(data []byte) (*score.Score, []string, error)
• func ImportFile(path string) (*score.Score, []string, error)

Constants

const DefaultProgram = 25

DefaultProgram is the General MIDI program assumed for parts with no midi-instrument declaration: 25, steel-string acoustic guitar, matching the text format's and MIDI importer's default.

const MaxTicks = 100_000_000

MaxTicks caps the score extent the import will accept — about 14 hours of 4/4 at 120 BPM. barSpecs allocates one barSpec per bar from tick 0 to the score's end, so a single hostile <duration> (or time signature) could otherwise turn the layout into an unbounded allocation loop.

Functions

func Import

func Import(data []byte) (*score.Score, []string, error)

Import parses a MusicXML document into a Score, returning human-readable warnings for everything the import changed, skipped, or inferred. The container is sniffed from the bytes — a ZIP signature means .mxl, anything else is parsed as uncompressed XML — so the caller's file extension does not matter. The first part containing notes becomes the RoleUser track, later ones RoleBacking. The result always passes score.Validate.

func ImportFile

func ImportFile(path string) (*score.Score, []string, error)

ImportFile reads path and imports it via Import.