.. _stdlib_strudel_midi:

================
MIDI file parser
================

.. das:module:: strudel_midi

Module strudel_midi



++++++++++++
Enumerations
++++++++++++

.. _enum-strudel_midi-MidiEventKind:

.. das:attribute:: MidiEventKind

:Values: * **midi_note_off** = 0 - Note released.

         * **midi_note_on** = 1 - Note pressed (velocity > 0) or released (velocity == 0).

         * **midi_control_change** = 2 - Controller value change (CC). data1 = controller number, data2 = value.

         * **midi_program_change** = 3 - Instrument/program change. data1 = program number.

         * **midi_pitch_bend** = 4 - Pitch bend. data1 = LSB, data2 = MSB (14-bit value, 8192 = center).

         * **midi_tempo** = 5 - Tempo change (meta event). tempo field = microseconds per quarter note.

         * **midi_end_of_track** = 6 - End of track marker.

         * **midi_other** = 7 - Unrecognized or unsupported MIDI event.




++++++++++
Structures
++++++++++

.. _struct-strudel_midi-MidiEvent:

.. das:attribute:: MidiEvent

:Fields: * **tick** : int - Absolute tick position within the track.

         * **kind** :  :ref:`MidiEventKind <enum-strudel_midi-MidiEventKind>` - Event type.

         * **channel** : int - MIDI channel (0-15).

         * **data1** : int - First data byte (note number, controller number, or program number).

         * **data2** : int - Second data byte (velocity, controller value, or pitch bend MSB).

         * **tempo** : int - Microseconds per quarter note (only valid for midi_tempo events).

         * **seq** : int - Sequence number for stable sort ordering.



.. _struct-strudel_midi-MidiTrack:

.. das:attribute:: MidiTrack

struct MidiTrack

.. _struct-strudel_midi-MidiFile:

.. das:attribute:: MidiFile

:Fields: * **format** : int - MIDI format (0 = single track, 1 = multi-track synchronous, 2 = multi-track asynchronous).

         * **ticks_per_qn** : int - Ticks per quarter note (time resolution).

         * **tracks** : array< :ref:`MidiTrack <struct-strudel_midi-MidiTrack>`> - Array of tracks.




+++++++
Parsing
+++++++

  *  :ref:`load_midi (path: string) : MidiFile <function-strudel_midi_load_midi_string>`
  *  :ref:`parse_midi (data: array\<uint8\>) : MidiFile <function-strudel_midi_parse_midi_array_ls_uint8_gr_>`
  *  :ref:`parse_midi_track (data: array\<uint8\>; var cursor: int&) : MidiTrack <function-strudel_midi_parse_midi_track_array_ls_uint8_gr__int_ref_>`

.. _function-strudel_midi_load_midi_string:

.. das:function:: load_midi(path: string) : MidiFile

Load and parse a MIDI file from disk.


:Arguments: * **path** : string

.. _function-strudel_midi_parse_midi_array_ls_uint8_gr_:

.. das:function:: parse_midi(data: array<uint8>) : MidiFile

Parse MIDI data from a byte array into a MidiFile structure.


:Arguments: * **data** : array<uint8>

.. _function-strudel_midi_parse_midi_track_array_ls_uint8_gr__int_ref_:

.. das:function:: parse_midi_track(data: array<uint8>; cursor: int&) : MidiTrack

Parse a single MTrk chunk starting at cursor, returning the track with all events.


:Arguments: * **data** : array<uint8>

            * **cursor** : int\ &


++++++++++++++++
Track operations
++++++++++++++++

  *  :ref:`merge_tracks (midi: MidiFile) : array\<MidiEvent\> <function-strudel_midi_merge_tracks_MidiFile>`

.. _function-strudel_midi_merge_tracks_MidiFile:

.. das:function:: merge_tracks(midi: MidiFile) : array<MidiEvent>

Merge all tracks into a single sorted event list for sequential playback.


:Arguments: * **midi** :  :ref:`MidiFile <struct-strudel_midi-MidiFile>`


++++++++++++++
Binary readers
++++++++++++++

  *  :ref:`read_byte (data: array\<uint8\>; var cursor: int&) : int <function-strudel_midi_read_byte_array_ls_uint8_gr__int_ref_>`
  *  :ref:`read_u16 (data: array\<uint8\>; var cursor: int&) : int <function-strudel_midi_read_u16_array_ls_uint8_gr__int_ref_>`
  *  :ref:`read_u32 (data: array\<uint8\>; var cursor: int&) : int <function-strudel_midi_read_u32_array_ls_uint8_gr__int_ref_>`
  *  :ref:`read_vlq (data: array\<uint8\>; var cursor: int&) : int <function-strudel_midi_read_vlq_array_ls_uint8_gr__int_ref_>`

.. _function-strudel_midi_read_byte_array_ls_uint8_gr__int_ref_:

.. das:function:: read_byte(data: array<uint8>; cursor: int&) : int

Read a single byte from data at cursor, advancing cursor. Returns -1 on EOF.


:Arguments: * **data** : array<uint8>

            * **cursor** : int\ &

.. _function-strudel_midi_read_u16_array_ls_uint8_gr__int_ref_:

.. das:function:: read_u16(data: array<uint8>; cursor: int&) : int

Read a big-endian 16-bit unsigned integer. Returns -1 on EOF.


:Arguments: * **data** : array<uint8>

            * **cursor** : int\ &

.. _function-strudel_midi_read_u32_array_ls_uint8_gr__int_ref_:

.. das:function:: read_u32(data: array<uint8>; cursor: int&) : int

Read a big-endian 32-bit unsigned integer. Returns -1 on EOF.


:Arguments: * **data** : array<uint8>

            * **cursor** : int\ &

.. _function-strudel_midi_read_vlq_array_ls_uint8_gr__int_ref_:

.. das:function:: read_vlq(data: array<uint8>; cursor: int&) : int

Read a MIDI variable-length quantity (up to 4 bytes). Returns -1 on EOF.


:Arguments: * **data** : array<uint8>

            * **cursor** : int\ &