circuitpython-tmidi 2.0.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

{circuitpython_tmidi-2.0.0.dist-info → circuitpython_tmidi-3.0.0.dist-info}/METADATA

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: circuitpython-tmidi
-Version: 2.0.0
+Version: 3.0.0
 Summary: MIDI library for CircuitPython
 Author-email: Tod Kurt <tod@todbot.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/todbot/CircuitPython_TMIDI
 Keywords: adafruit,blinka,circuitpython,micropython,tmidi,midi
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Embedded Systems
 Classifier: Topic :: System :: Hardware
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Description-Content-Type: text/x-rst
 License-File: LICENSE
@@ -37,6 +36,100 @@ Introduction
 
 MIDI library for CircuitPython
 
+TMIDI is a MIDI library for CircuitPython / MicroPython. It attempts to
+be a provide a simpler API and perform faster, especially for MIDI parsing,
+compared to ``adafruit_midi`` (`adafruit_midi github <https://github.com/adafruit/Adafruit_CircuitPython_MIDI/>`_)
+TMIDI is derived from  ``winterbloom_smolmidi``
+(`smolmidi github <https://github.com/wntrblm/Winterbloom_SmolMIDI>`_)
+by Thea Flowers for Winterbloom.
+
+Like ``adafruit_midi``, TMIDI works on CircuitPython's ``usb_midi`` and ``busio.UART``,
+or any stream-like object that supports ``.readinto()`` and ``.write()``
+
+Usage Example
+=============
+
+Sending MIDI over USB. Channels are 0-indexed, so ``channel=0`` is
+MIDI channel 1:
+
+.. code-block:: python
+
+    import time
+    import usb_midi
+    import tmidi
+
+    midi = tmidi.MIDI(midi_out=usb_midi.ports[1])
+
+    while True:
+        midi.send(tmidi.Message(tmidi.NOTE_ON, 60, 100, channel=0))
+        time.sleep(0.5)
+        midi.send(tmidi.Message(tmidi.NOTE_OFF, 60, 0, channel=0))
+        time.sleep(0.5)
+
+Receiving MIDI over USB. ``receive()`` returns ``None`` when nothing
+has arrived:
+
+.. code-block:: python
+
+    import usb_midi
+    import tmidi
+
+    midi = tmidi.MIDI(midi_in=usb_midi.ports[0])
+
+    while True:
+        if msg := midi.receive():
+            if msg.type == tmidi.NOTE_ON:
+                print("note on:", msg.note, msg.velocity, msg.channel)
+            else:
+                print(msg)
+
+
+Callbacks
+=========
+
+Instead of ``receive()``, register functions for the message types you want
+and call ``poll()``. No ``Message`` objects are allocated.
+
+.. code-block:: python
+
+    def note_on(channel, note, velocity):
+        print("note on:", channel, note, velocity)
+
+    midi.on(tmidi.NOTE_ON, note_on)
+    while True:
+        midi.poll()
+
+See ``examples/tmidi_simple_poll.py`` for a full example.
+
+Turbo parser
+============
+
+TMIDI runs entirely in Python, but uses a faster ``@micropython.viper``
+parser when your firmware can load native code. The parsers ship inside the
+``tmidi/`` library folder as ``tmidi_kernel.<arch>.mpy``, and CircuitPython
+picks the one for your board. ``tmidi.ENGINE`` says which parser is in use.
+
+TMIDI 3.0 is a folder, ``lib/tmidi/``, instead of a single ``lib/tmidi.mpy``.
+Delete an old ``lib/tmidi.mpy`` when upgrading.
+
+======================  =====================================
+``tmidi_kernel`` file   Boards
+======================  =====================================
+``armv6m``              RP2040
+``armv7emsp``           SAMD51, nRF52840, RP2350, STM32F4
+``xtensawin``           ESP32-S2, ESP32-S3
+``rv32imc``             ESP32-C3, C5, C6
+======================  =====================================
+
+To rebuild them from ``src/tmidi_turbo.py``, use an ``mpy-cross`` from the
+CircuitPython version they will run on. The files land in ``tmidi/``:
+
+.. code-block:: shell
+
+    cd src
+    make MPY_CROSS=path/to/circuitpython/mpy-cross/build/mpy-cross
+
+
 
 Dependencies
 =============
@@ -99,28 +192,6 @@ Or the following command to update an existing version:
 
     circup update
 
-Usage Example
-=============
-
-.. code-block:: python
-
-    import usb_midi
-    import tmidi
-
-    midi_usb = tmidi.MIDI(midi_in=usb_midi.ports[0], midi_out=usb_midi.ports[1])
-
-    def send_midi_panic(midi_channel=1):
-        ch = midi_channel-1
-        msg = tmidi.Message(tmidi.NOTE_OFF, channel=ch)  # channels are 0-indexed
-        for notenum in range(128):
-            msg.note = notenum
-            msg.velocity = 0
-            midi_usb.send(msg)
-            time.sleep(0.01)
-    }
-
-    send_midi_panic()
-
 
 Documentation
 =============
@@ -132,8 +203,7 @@ For information on building library documentation, please check out
 Testing
 =======
 
-Install ``pytest`` with ``pip3 install pytest --upgrade`` and run ``pytest -v``
-To build docs:
+Install ``pytest`` with ``pip3 install pytest circuitpython-mocks --upgrade`` and run ``pytest -v``
 
 Contributing
 ============

circuitpython_tmidi-3.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+circuitpython_tmidi-3.0.0.dist-info/licenses/LICENSE,sha256=jhhRyxpqyQxyF_D6SzY2-jCA5v8Z8JXfezCtxBS85CM,1075
+tmidi/__init__.py,sha256=zYkXV7fPwddPiDMCsSXOANIgH9TCFKcXzatkBQoc9x4,19833
+tmidi/tmidi_kernel.armv6m.mpy,sha256=OCmHancSoUi1NzRiPc7gUmBJlMsdlNh0rWwp-oSh88U,1238
+tmidi/tmidi_kernel.armv7emsp.mpy,sha256=X-Go1gkD--_t3ZldGvl8i9HUJ-W3r5IKijI-lZZLLRA,992
+tmidi/tmidi_kernel.rv32imc.mpy,sha256=_XAqmSPDTpmEngrJ5m7rorq_mh5snhellBiPYIgVCds,1344
+tmidi/tmidi_kernel.xtensawin.mpy,sha256=KMWvzgLML75mXVZ05PeWsjlKqVNagJOLj2kqBEHnljY,1145
+circuitpython_tmidi-3.0.0.dist-info/METADATA,sha256=UCS6X4Xa_DRFq5PwPHxiwlLi_gOo00Q-UNx5xd9pnFE,6575
+circuitpython_tmidi-3.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+circuitpython_tmidi-3.0.0.dist-info/top_level.txt,sha256=ey35b95sYIkXnGcYlLMoLxC4R4Z_waH1rnvn3ntCW5o,6
+circuitpython_tmidi-3.0.0.dist-info/RECORD,,

{circuitpython_tmidi-2.0.0.dist-info → circuitpython_tmidi-3.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

tmidi/__init__.py

@@ -0,0 +1,643 @@
+# SPDX-FileCopyrightText: Copyright (c) 2019 Alethea Flowers for Winterbloom
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+#
+# SPDX-License-Identifier: MIT
+"""
+`tmidi`
+================================================================================
+
+MIDI library for CircuitPython
+
+
+* Author(s): Tod Kurt, with code from Alethea Flowers for Winterbloom
+
+* Portions of this library come from Winterbloom_SmolMIDI:
+  https://github.com/wntrblm/Winterbloom_SmolMIDI
+
+Implementation Notes
+--------------------
+
+**Hardware:**
+
+* Native USB for USB MIDI
+* UART for Serial MIDI
+* PIO-USB or MAX3421E USB Host for USB Host MIDI
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://circuitpython.org/downloads
+
+"""
+
+# imports
+
+__version__ = "3.0.0"
+__repo__ = "https://github.com/todbot/CircuitPython_TMIDI.git"
+
+# Portions of this library come from Winterbloom_SmolMIDI:
+#
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Alethea Flowers for Winterbloom
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+from array import array
+
+from micropython import const
+
+# Prebuilt per chip as tmidi_kernel.<arch>.mpy from src/tmidi_turbo.py.
+# Missing on Blinka and on firmware without native code.
+try:
+    from tmidi.tmidi_kernel import parse as _kernel_parse
+except (ImportError, ValueError):
+    _kernel_parse = None
+
+ENGINE = "Python" if _kernel_parse is None else "viper"
+"""``"viper"`` when the turbo parser loaded, else ``"Python"``."""
+
+# Message type constants.
+NOTE_OFF = const(0x80)
+"""Note Off"""
+NOTE_ON = const(0x90)
+"""Note On"""
+AFTERTOUCH = const(0xA0)
+"""Aftertouch"""
+CONTROLLER_CHANGE = CC = const(0xB0)
+"""Controller Change"""
+PROGRAM_CHANGE = const(0xC0)
+"""Program Change"""
+CHANNEL_PRESSURE = const(0xD0)
+"""Channel Pressure"""
+PITCH_BEND = const(0xE0)
+"""Pitch Bend"""
+SYSTEM_EXCLUSIVE = SYSEX = const(0xF0)
+"""Sysex"""
+SONG_POSITION = const(0xF2)
+"""Song Position"""
+SONG_SELECT = const(0xF3)
+"""Song Select"""
+BUS_SELECT = const(0xF5)
+"""BUS Select"""
+TUNE_REQUEST = const(0xF6)
+"""Tune Request"""
+SYSEX_END = const(0xF7)
+"""Sysex End"""
+CLOCK = const(0xF8)
+"""Clock"""
+TICK = const(0xF9)
+"""Tick"""
+START = const(0xFA)
+"""Start"""
+CONTINUE = const(0xFB)
+"""Continue"""
+STOP = const(0xFC)
+"""Stop"""
+ACTIVE_SENSING = const(0xFE)
+"""Active Sensing"""
+SYSTEM_RESET = const(0xFF)
+"""System Reset"""
+
+_MSG_DATA_LEN = {
+    NOTE_OFF: 2,
+    NOTE_ON: 2,
+    AFTERTOUCH: 2,
+    CC: 2,
+    PITCH_BEND: 2,
+    SONG_POSITION: 2,
+    PROGRAM_CHANGE: 1,
+    CHANNEL_PRESSURE: 1,
+    SONG_SELECT: 1,
+    BUS_SELECT: 1,
+}
+
+# Pre-allocated scratch buffer for __bytes__() — avoids per-call list allocation.
+# Safe because CircuitPython is single-threaded.
+_msg_buf = bytearray(3)
+
+_MSG_TYPE_NAMES = {
+    NOTE_OFF: "NoteOff",
+    NOTE_ON: "NoteOn",
+    AFTERTOUCH: "Aftertouch",
+    CC: "CC",
+    PROGRAM_CHANGE: "ProgramChange",
+    CHANNEL_PRESSURE: "ChannelPressure",
+    PITCH_BEND: "PitchBend",
+    SYSEX: "Sysex",
+    SONG_POSITION: "SongPosition",
+    SONG_SELECT: "SongSelect",
+    BUS_SELECT: "BusSelect",
+    TUNE_REQUEST: "TuneRequest",
+    SYSEX_END: "SysexEnd",
+    CLOCK: "Clock",
+    TICK: "Tick",
+    START: "Start",
+    CONTINUE: "Continue",
+    STOP: "Stop",
+    ACTIVE_SENSING: "ActiveSensing",
+    SYSTEM_RESET: "SystemReset",
+}
+
+
+def _is_channel_message(status_byte):
+    return status_byte >= NOTE_OFF and status_byte < SYSEX
+
+
+# Keep in sync with the _ST_ slots in src/tmidi_turbo.py
+_ST_RD = const(0)
+_ST_WR = const(1)
+_ST_STATUS = const(2)
+_ST_NEED = const(3)
+_ST_DATA0 = const(4)
+_ST_SX_LEN = const(5)
+_ST_SX_CAP = const(6)
+_ST_ERRORS = const(7)
+_ST_RUNNING = const(8)
+_ST_RUNNING_ON = const(9)
+_ST_SIZE = const(10)
+
+_NEED_ONE = const(1)
+_NEED_FIRST = const(2)
+_NEED_SECOND = const(3)
+
+# status bytes the parser tests for, keep in sync with src/tmidi_turbo.py
+_B_STATUS = const(0x80)  # lowest status byte, data bytes are below
+_B_SYSTEM = const(0xF0)  # first system message, channel messages are below
+_B_SYSEX = const(0xF0)
+_B_SONG_POSITION = const(0xF2)
+_B_SONG_SELECT = const(0xF3)
+_B_BUS_SELECT = const(0xF5)
+_B_SYSEX_END = const(0xF7)
+_B_REALTIME = const(0xF8)  # first real-time message
+_B_ONE_DATA_MASK = const(0xE0)
+_B_ONE_DATA = const(0xC0)  # PROGRAM_CHANGE and CHANNEL_PRESSURE, masked
+
+_READ_SIZE = const(64)
+_MAX_SYSEX = const(65535)
+
+_NO_SYSEX = bytearray(0)
+
+
+def _parse_py(buf, st, sx):
+    """Return next message from buf as status<<16|data0<<8|data1, 0 if drained.
+
+    Keep in sync with the viper version in src/tmidi_turbo.py.
+    """
+    rd = st[_ST_RD]
+    wr = st[_ST_WR]
+    status = st[_ST_STATUS]
+    need = st[_ST_NEED]
+
+    while rd < wr:
+        b = buf[rd]
+        rd += 1
+
+        # real-time can land inside any message and must not disturb it
+        if b >= _B_REALTIME:
+            st[_ST_RD] = rd
+            st[_ST_STATUS] = status
+            st[_ST_NEED] = need
+            return b << 16
+
+        if b >= _B_STATUS:
+            if b == _B_SYSEX_END and status == _B_SYSEX:
+                st[_ST_RD] = rd
+                st[_ST_STATUS] = 0
+                st[_ST_NEED] = 0
+                return _B_SYSEX << 16 | st[_ST_SX_LEN]
+
+            if status != 0:
+                st[_ST_ERRORS] = (st[_ST_ERRORS] + 1) & 0xFFFF
+
+            status = b
+            if b < _B_SYSTEM:
+                if st[_ST_RUNNING_ON] != 0:
+                    st[_ST_RUNNING] = b
+                if (b & _B_ONE_DATA_MASK) == _B_ONE_DATA:
+                    need = _NEED_ONE
+                else:
+                    need = _NEED_FIRST
+                continue
+
+            st[_ST_RUNNING] = 0
+            if b == _B_SYSEX:
+                need = 0
+                st[_ST_SX_LEN] = 0
+                continue
+            if b == _B_SONG_POSITION:
+                need = _NEED_FIRST
+                continue
+            if b == _B_SONG_SELECT or b == _B_BUS_SELECT:
+                need = _NEED_ONE
+                continue
+
+            st[_ST_RD] = rd
+            st[_ST_STATUS] = 0
+            st[_ST_NEED] = 0
+            return b << 16
+
+        if status == _B_SYSEX:
+            n = st[_ST_SX_LEN]
+            if n < st[_ST_SX_CAP]:
+                sx[n] = b
+                st[_ST_SX_LEN] = n + 1
+            continue
+
+        if status == 0:
+            status = st[_ST_RUNNING]
+            if status == 0:
+                st[_ST_ERRORS] = (st[_ST_ERRORS] + 1) & 0xFFFF
+                continue
+            if (status & _B_ONE_DATA_MASK) == _B_ONE_DATA:
+                need = _NEED_ONE
+            else:
+                need = _NEED_FIRST
+
+        if need == _NEED_FIRST:
+            st[_ST_DATA0] = b
+            need = _NEED_SECOND
+            continue
+
+        st[_ST_RD] = rd
+        st[_ST_STATUS] = 0
+        st[_ST_NEED] = 0
+        if need == _NEED_SECOND:
+            return status << 16 | st[_ST_DATA0] << 8 | b
+        return status << 16 | b << 8
+
+    st[_ST_RD] = rd
+    st[_ST_STATUS] = status
+    st[_ST_NEED] = need
+    return 0
+
+
+class Message:
+    """
+    MIDI Message.
+
+    :param mtype: The type of message, e.g. tmidi.NOTE_ON.
+    :param data0: The first data byte for this message,
+        e.g. the note number as an ``int`` (0-127) for NOTE_ON messages.
+    :param data1: The second data byte for this message,
+        e.g. the velocity (0-127) for NOTE_ON messages.
+    :param channel: The MIDI channel for this message, if applicable (0-15)
+
+    Example of creating Messages:
+
+    .. code-block:: python
+
+        # create Note On middle-C message on ch 1 (0-indexed)
+        m = Message(tmidi.NOTE_ON, 60, 127, channel=0)
+        # create CC 74 with val 63 on ch 4
+        m = Message(tmidi.CC, 74, 63, channel=4-1)
+        # create a pitch bend full up on ch 1
+        m = Message(tmidi.PITCH_BEND, 8191)
+
+    Example of creating accessing Message attributes:
+
+    .. code-block:: python
+
+        if msg := midi.receive():
+            if msg.type == tmidi.NOTE_ON:
+              print("note on:", msg.note, msg.velocity)
+            elif msg.type == tmidi.NOTE_OFF:
+              print("note off:", msg.note, msg.velocity)
+            elif msg.type == tmidi.PROGRAM_CHANGE:
+              print("program change:", msg.value)
+    """
+
+    def __init__(self, mtype=SYSTEM_RESET, data0=0, data1=0, channel=0):
+        self.type = mtype
+        self.channel = channel
+        self.data0 = data0
+        self.data1 = data1
+        if mtype == PITCH_BEND and data1 == 0 and not (0 <= data0 <= 0x7F):
+            self.pitch_bend = data0
+
+    def __bytes__(self):
+        status_byte = self.type
+        if _is_channel_message(status_byte):
+            status_byte |= self.channel
+        _msg_buf[0] = status_byte
+        n = _MSG_DATA_LEN.get(self.type, 0)
+        if n == 2:
+            _msg_buf[1] = self.data0
+            _msg_buf[2] = self.data1
+            return bytes(_msg_buf)
+        if n == 1:
+            _msg_buf[1] = self.data0
+            return bytes(_msg_buf[:2])
+        return bytes(_msg_buf[:1])
+
+    def __repr__(self):
+        return self.__str__()
+
+    def __str__(self):
+        mtype = self.type
+        type_str = "Message(" + _MSG_TYPE_NAMES.get(mtype, "Unknown")
+        ch_str = "ch:%d" % self.channel if _is_channel_message(mtype) else "-"
+        if mtype == PITCH_BEND:
+            return "%s %s %d)" % (type_str, ch_str, self.pitch_bend)
+        if mtype == SYSEX:
+            if self.data0:
+                return "%s %d bytes)" % (type_str, self.data0)
+            return "%s)" % type_str
+        n = _MSG_DATA_LEN.get(mtype, 0)
+        if n == 2:
+            return "%s %s %d %d)" % (type_str, ch_str, self.data0, self.data1)
+        if n == 1:
+            return "%s %s %d)" % (type_str, ch_str, self.data0)
+        return "%s)" % type_str
+
+    @property
+    def note(self):
+        """MIDI note number of message (only valid for NOTE_ON/NOTE_OFF msgs)"""
+        return self.data0
+
+    @note.setter
+    def note(self, notenum):
+        self.data0 = notenum
+
+    @property
+    def velocity(self):
+        """MIDI velocity of message (only valid for NOTE_ON/NOTE_OFF msgs)"""
+        return self.data1
+
+    @velocity.setter
+    def velocity(self, vel):
+        self.data1 = vel
+
+    @property
+    def pitch_bend(self):
+        """Pitch bend value of message (only valid for PITCH_BEND msgs)"""
+        return (self.data1 << 7 | self.data0) - 8192
+
+    @pitch_bend.setter
+    def pitch_bend(self, pbval):
+        pbval += 8192
+        self.data0 = pbval & 0x7F
+        self.data1 = pbval >> 7
+
+    @property
+    def value(self):
+        """Message value, only valid for len1 messages (Program Change, etc)"""
+        return self.data0
+
+    @value.setter
+    def value(self, val):
+        self.data0 = val
+
+
+class MIDI:
+    """
+    MIDI Parser, receiver and sender
+    ``midi_in`` or ``midi_out`` *must* be set or both together.
+
+    :param midi_in: an object which implements ``read(length)``,
+        set to ``usb_midi.ports[0]`` for USB MIDI, default None.
+    :param midi_out: an object which implements ``write(buffer, length)``,
+        set to ``usb_midi.ports[1]`` for USB MIDI, default None.
+    :param bool enable_running_status: Allow running status messages to work, default False.
+    :param bytearray sysex_buffer: Optional pre-allocated buffer for capturing SysEx payloads.
+        When provided, received SysEx payload bytes are written into this buffer and
+        ``msg.data0`` on the returned message holds the number of bytes written.
+        If the payload exceeds the buffer length, the overflow is consumed and discarded
+        so the stream stays in sync. When ``None`` (default), SysEx payloads are discarded
+        and ``msg.data0`` is 0.
+    :param bool turbo: Use the viper parser if it loaded (see ``ENGINE``), default True.
+
+    Example of receiving with callbacks, which avoids allocating ``Message`` objects:
+
+    .. code-block:: python
+
+        import usb_midi
+        import tmidi
+
+        def note_on(channel, note, velocity):
+            print("note on:", channel, note, velocity)
+
+        midi = tmidi.MIDI(midi_in=usb_midi.ports[0])
+        midi.on(tmidi.NOTE_ON, note_on)
+
+        while True:
+            midi.poll()
+
+    Example of receiving SysEx with payload capture:
+
+    .. code-block:: python
+
+        import usb_midi
+        import tmidi
+        sysex_buf = bytearray(128)
+        midi = tmidi.MIDI(midi_in=usb_midi.ports[0], sysex_buffer=sysex_buf)
+
+        while True:
+            if msg := midi.receive():
+                if msg.type == tmidi.SYSEX:
+                    payload = memoryview(sysex_buf)[: msg.data0]
+                    print("SysEx:", list(payload))
+
+    Example of sending MIDI over USB:
+
+    .. code-block:: python
+
+        import usb_midi
+        import tmidi
+        midi_usb = tmidi.MIDI(midi_out=usb_midi.ports[1])
+        msg_on = tmidi.Message(tmidi.NOTE_ON, notenum, velocity)
+        midi_usb.send(msg_on)
+
+    Example of sending MIDI over UART (TRS or 5-pin):
+
+    .. code-block:: python
+
+        import board
+        import busio
+        import tmidi
+        uart = busio.UART(tx=board.TX, rx=board.RX, timeout=0.001)
+        midi_uart = tmidi.MIDI(midi_out=uart)
+        msg_on = tmidi.Message(tmidi.NOTE_ON, notenum, velocity)
+        midi_uart.send(msg_on)
+
+    Example of receiving MIDI:
+
+    .. code-block:: python
+
+        import board
+        import busio
+        import usb_midi
+        import tmidi
+        uart = busio.UART(tx=board.TX, rx=board.RX, timeout=0.001)
+        midi_uart = tmidi.MIDI(midi_in=uart, midi_out=uart)
+        midi_usb = tmidi.MIDI(midi_in=usb_midi.ports[0], midi_out=usb_midi.ports[1])
+
+        while True:
+            if msg := midi_usb.receive():
+                print("usb midi:", msg)
+            if msg := midi_uart.receive():
+                print("uart midi:", msg)
+    """
+
+    def __init__(
+        self,
+        midi_in=None,
+        midi_out=None,
+        enable_running_status=False,
+        sysex_buffer=None,
+        turbo=True,
+    ):
+        self._in_port = midi_in
+        self._out_port = midi_out
+        self._has_in_waiting = hasattr(midi_in, "in_waiting")
+        self._parse = _kernel_parse if turbo and _kernel_parse else _parse_py
+        self._callbacks = {}
+
+        self._bulk_read = True
+        self._one = bytearray(1)
+        self._buf = bytearray(_READ_SIZE)
+        self._sx = _NO_SYSEX if sysex_buffer is None else sysex_buffer
+        self._st = array("H", [0] * _ST_SIZE)
+        self._st[_ST_SX_CAP] = min(len(self._sx), _MAX_SYSEX)
+        self._st[_ST_RUNNING_ON] = 1 if enable_running_status else 0
+
+    @property
+    def error_count(self):
+        """Number of errors encountered when parsing received messages"""
+        return self._st[_ST_ERRORS]
+
+    def _fill(self):
+        n = _READ_SIZE
+        if self._has_in_waiting:
+            # a large readinto on UART would block toward its timeout
+            n = min(self._in_port.in_waiting, _READ_SIZE)
+            if not n:
+                return 0
+        if self._bulk_read:
+            try:
+                n = self._in_port.readinto(self._buf, n) or 0
+            except TypeError:
+                # adafruit_usb_host_midi has readinto(buf), which must be filled exactly
+                self._bulk_read = False
+                return self._fill()
+        else:
+            n = self._in_port.readinto(self._one) or 0
+            if n:
+                self._buf[0] = self._one[0]
+        self._st[_ST_RD] = 0
+        self._st[_ST_WR] = n
+        return n
+
+    def receive(self):
+        """Read from MIDI port, parse that data and return the next MIDI message.
+        Does not wait: a partly received message is kept until the rest arrives.
+
+        :returns Message object: Returns object or None for nothing.
+        """
+        parse = self._parse
+        buf = self._buf
+        st = self._st
+        sx = self._sx
+
+        r = parse(buf, st, sx)
+        while not r:
+            if not self._fill():
+                return None
+            r = parse(buf, st, sx)
+
+        status = r >> 16
+        if status < SYSEX:
+            return Message(status & 0xF0, (r >> 8) & 0xFF, r & 0xFF, status & 0x0F)
+        if status == SYSEX:
+            return Message(SYSEX, r & 0xFFFF)
+        return Message(status, (r >> 8) & 0xFF, r & 0xFF)
+
+    def on(self, mtype, func):
+        """Register a function to be called by :meth:`poll` for a type of message.
+        There is one function per message type.
+
+        :param int mtype: The type of message, e.g. ``tmidi.NOTE_ON``.
+        :param func: Called as ``func(channel, data0, data1)`` with the raw data bytes.
+            ``channel`` is 0 for system messages. For ``tmidi.SYSEX``, ``data0`` is
+            the number of bytes written to ``sysex_buffer``.
+            Use ``None`` to unregister.
+        """
+        if func is None:
+            self._callbacks.pop(mtype, None)
+        else:
+            self._callbacks[mtype] = func
+
+    def poll(self, limit=32):
+        """Parse waiting MIDI data, calling functions registered with :meth:`on`.
+
+        :param int limit: Most messages to handle, so a busy port can't starve
+            the main loop.
+        :returns int: Number of messages parsed
+        """
+        parse = self._parse
+        buf = self._buf
+        st = self._st
+        sx = self._sx
+        callbacks = self._callbacks
+
+        count = 0
+        while count < limit:
+            r = parse(buf, st, sx)
+            while not r:
+                if not self._fill():
+                    return count
+                r = parse(buf, st, sx)
+            count += 1
+
+            status = r >> 16
+            if status < SYSEX:
+                func = callbacks.get(status & 0xF0)
+                if func:
+                    func(status & 0x0F, (r >> 8) & 0xFF, r & 0xFF)
+            elif status == SYSEX:
+                func = callbacks.get(SYSEX)
+                if func:
+                    func(0, r & 0xFFFF, 0)
+            else:
+                func = callbacks.get(status)
+                if func:
+                    func(0, (r >> 8) & 0xFF, r & 0xFF)
+        return count
+
+    def send(self, msg, channel=None):
+        """Send a MIDI message.
+
+        :param msg: Either a Message object or a sequence (list) of Message objects.
+            The channel property will be *updated* as a side-effect of sending message(s).
+        :param int channel: Channel number, if not set, the msg's channel will be used.
+        """
+
+        if isinstance(msg, Message):
+            if channel is not None:
+                msg.channel = channel
+            # bytes(object) does not work in uPy
+            data = msg.__bytes__()
+        else:
+            data = bytearray()
+            for each_msg in msg:
+                if channel is not None:
+                    each_msg.channel = channel
+                data.extend(each_msg.__bytes__())
+
+        self._out_port.write(data, len(data))

circuitpython_tmidi-2.0.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-tmidi.py,sha256=o0wX5I5xUPLpD9K6eAgSaewBZGPqSn8YT4eAukeeYU8,13086
-circuitpython_tmidi-2.0.0.dist-info/licenses/LICENSE,sha256=jhhRyxpqyQxyF_D6SzY2-jCA5v8Z8JXfezCtxBS85CM,1075
-circuitpython_tmidi-2.0.0.dist-info/METADATA,sha256=-X6m4y1dqA5NvLbJxIgQp2Dp20w9_1NByUMUSZBoD0w,4192
-circuitpython_tmidi-2.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-circuitpython_tmidi-2.0.0.dist-info/top_level.txt,sha256=ey35b95sYIkXnGcYlLMoLxC4R4Z_waH1rnvn3ntCW5o,6
-circuitpython_tmidi-2.0.0.dist-info/RECORD,,

tmidi.py

@@ -1,423 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2019 Alethea Flowers for Winterbloom
-# SPDX-FileCopyrightText: Copyright (c) 2024 Tod Kurt
-#
-# SPDX-License-Identifier: MIT
-"""
-`tmidi`
-================================================================================
-
-MIDI library for CircuitPython
-
-
-* Author(s): Tod Kurt, with code from Alethea Flowers for Winterbloom
-
-* Portions of this library come from Winterbloom_SmolMIDI:
-  https://github.com/wntrblm/Winterbloom_SmolMIDI
-
-Implementation Notes
---------------------
-
-**Hardware:**
-
-* Native USB for USB MIDI
-* UART for Serial MIDI
-* PIO-USB or MAX3421E USB Host for USB Host MIDI
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://circuitpython.org/downloads
-
-"""
-
-# imports
-
-__version__ = "2.0.0"
-__repo__ = "https://github.com/todbot/CircuitPython_TMIDI.git"
-
-# Portions of this library come from Winterbloom_SmolMIDI:
-#
-# The MIT License (MIT)
-#
-# Copyright (c) 2019 Alethea Flowers for Winterbloom
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
-
-from micropython import const
-
-# Message type constants.
-NOTE_OFF = const(0x80)
-"""Note Off"""
-NOTE_ON = const(0x90)
-"""Note On"""
-AFTERTOUCH = const(0xA0)
-"""Aftertouch"""
-CONTROLLER_CHANGE = CC = const(0xB0)
-"""Controller Change"""
-PROGRAM_CHANGE = const(0xC0)
-"""Program Change"""
-CHANNEL_PRESSURE = const(0xD0)
-"""Channel Pressure"""
-PITCH_BEND = const(0xE0)
-"""Pitch Bend"""
-SYSTEM_EXCLUSIVE = SYSEX = const(0xF0)
-"""Sysex"""
-SONG_POSITION = const(0xF2)
-"""Song Position"""
-SONG_SELECT = const(0xF3)
-"""Song Select"""
-BUS_SELECT = const(0xF5)
-"""BUS Select"""
-TUNE_REQUEST = const(0xF6)
-"""Tune Request"""
-SYSEX_END = const(0xF7)
-"""Sysex End"""
-CLOCK = const(0xF8)
-"""Clock"""
-TICK = const(0xF9)
-"""Tick"""
-START = const(0xFA)
-"""Start"""
-CONTINUE = const(0xFB)
-"""Continue"""
-STOP = const(0xFC)
-"""Stop"""
-ACTIVE_SENSING = const(0xFE)
-"""Active Sensing"""
-SYSTEM_RESET = const(0xFF)
-"""System Reset"""
-
-_LEN_0_MESSAGES = set(
-    [
-        TUNE_REQUEST,
-        SYSEX,
-        SYSEX_END,
-        CLOCK,
-        TICK,
-        START,
-        CONTINUE,
-        STOP,
-        ACTIVE_SENSING,
-        SYSTEM_RESET,
-    ]
-)
-_LEN_1_MESSAGES = set([PROGRAM_CHANGE, CHANNEL_PRESSURE, SONG_SELECT, BUS_SELECT])
-_LEN_2_MESSAGES = set([NOTE_OFF, NOTE_ON, AFTERTOUCH, CC, PITCH_BEND, SONG_POSITION])
-
-_MSG_TYPE_NAMES = {
-    NOTE_OFF: "NoteOff",
-    NOTE_ON: "NoteOn",
-    AFTERTOUCH: "Aftertouch",
-    CC: "CC",
-    PROGRAM_CHANGE: "ProgramChange",
-    CHANNEL_PRESSURE: "ChannelPressure",
-    PITCH_BEND: "PitchBend",
-    SYSEX: "Sysex",
-    SONG_POSITION: "SongPosition",
-    SONG_SELECT: "SongSelect",
-    BUS_SELECT: "BusSelect",
-    TUNE_REQUEST: "TuneRequest",
-    SYSEX_END: "SysexEnd",
-    CLOCK: "Clock",
-    TICK: "Tick",
-    START: "Start",
-    CONTINUE: "Continue",
-    STOP: "Stop",
-    ACTIVE_SENSING: "ActiveSensing",
-    SYSTEM_RESET: "SystemReset",
-}
-
-
-def _is_channel_message(status_byte):
-    return status_byte >= NOTE_OFF and status_byte < SYSEX
-
-
-def _read_byte(port):
-    while not (buf := port.read(1)):
-        pass
-    return buf[0]
-
-
-# def _read_n_bytes(port, buf, dest, num_bytes):
-#     while num_bytes:
-#         if port.readinto(buf):
-#             dest.append(buf[0])
-#             num_bytes -= 1
-
-
-# def _read_byte_works(port):
-#     while True:
-#         buf = port.read(1)
-#         if buf:
-#             return buf[0]
-
-
-class Message:
-    """
-    MIDI Message.
-
-    :param mtype: The type of message, e.g. tmidi.NOTE_ON.
-    :param data0: The first data byte for this message,
-        e.g. the note number as an ``int`` (0-127) for NOTE_ON messages.
-    :param data1: The second data byte for this message,
-        e.g. the velocity (0-127) for NOTE_ON messages.
-    :param channel: The MIDI channel for this message, if applicable (0-15)
-
-    Example of creating Messages:
-
-    .. code-block:: python
-
-        # create Note On middle-C message on ch 1 (0-indexed)
-        m = Message(tmidi.NOTE_ON, 60, 127, channel=0)
-        # create CC 74 with val 63 on ch 4
-        m = Message(tmidi.CC, 74, 63, channel=4-1)
-        # create a pitch bend full up on ch 1
-        m = Message(tmidi.PITCH_BEND, 8191)
-
-    Example of creating accessing Message attributes:
-
-    .. code-block:: python
-
-        if msg := midi.receive():
-            if msg.type == tmidi.NOTE_ON:
-              print("note on:", msg.note, msg.velocity)
-            elif msg.type == tmidi.NOTE_OFF:
-              print("note off:", msg.note, msg.velocity)
-            elif msg.type == tmidi.PROGRAM_CHANGE:
-              print("program change:", msg.value)
-    """
-
-    def __init__(self, mtype=SYSTEM_RESET, data0=0, data1=0, channel=0):
-        self.type = mtype
-        self.channel = channel
-        self.data0 = data0
-        self.data1 = data1
-        if mtype == PITCH_BEND and data1 == 0:
-            self.pitch_bend = data0
-
-    def __bytes__(self):
-        status_byte = self.type
-        if _is_channel_message(status_byte):
-            status_byte |= self.channel
-        if self.type in _LEN_2_MESSAGES:
-            return bytes([status_byte, self.data0, self.data1])
-        elif self.type in _LEN_1_MESSAGES:
-            return bytes([status_byte, self.data0])
-        return bytes([status_byte])
-
-    def __repr__(self):
-        return self.__str__()
-
-    def __str__(self):
-        mtype = self.type
-        type_str = "Message(" + _MSG_TYPE_NAMES.get(mtype, "Unknown")
-        ch_str = "ch:%d" % self.channel if _is_channel_message(mtype) else "-"
-        if mtype == PITCH_BEND:
-            return "%s %s %d)" % (type_str, ch_str, self.pitch_bend)
-        if mtype in _LEN_2_MESSAGES:
-            return "%s %s %d %d)" % (type_str, ch_str, self.data0, self.data1)
-        if mtype in _LEN_1_MESSAGES:
-            return "%s %s %d)" % (type_str, ch_str, self.data0)
-        return "%s)" % type_str
-
-    @property
-    def note(self):
-        """MIDI note number of message (only valid for NOTE_ON/NOTE_OFF msgs)"""
-        return self.data0
-
-    @note.setter
-    def note(self, notenum):
-        self.data0 = notenum
-
-    @property
-    def velocity(self):
-        """MIDI velocity of message (only valid for NOTE_ON/NOTE_OFF msgs)"""
-        return self.data1
-
-    @velocity.setter
-    def velocity(self, vel):
-        self.data1 = vel
-
-    @property
-    def pitch_bend(self):
-        """Pitch bend value of message (only valid for PITCH_BEND msgs)"""
-        return (self.data1 << 7 | self.data0) - 8192
-
-    @pitch_bend.setter
-    def pitch_bend(self, pbval):
-        pbval += 8192
-        self.data0 = pbval & 0x7F
-        self.data1 = pbval >> 7
-
-    @property
-    def value(self):
-        """Message value, only valid for len1 messages (Program Change, etc)"""
-        return self.data0
-
-    @value.setter
-    def value(self, val):
-        self.data0 = val
-
-
-class MIDI:
-    """
-    MIDI Parser, receiver and sender
-    ``midi_in`` or ``midi_out`` *must* be set or both together.
-
-    :param midi_in: an object which implements ``read(length)``,
-        set to ``usb_midi.ports[0]`` for USB MIDI, default None.
-    :param midi_out: an object which implements ``write(buffer, length)``,
-        set to ``usb_midi.ports[1]`` for USB MIDI, default None.
-    :param bool enable_running_status: Allow running status messages to work, default False.
-
-    Example of sending MIDI over USB:
-
-    .. code-block:: python
-
-        import usb_midi
-        import tmidi
-        midi_usb = tmidi.MIDI(midi_out=usb_midi.ports[1])
-        msg_on = tmidi.Message(tmidi.NOTE_ON, notenum, velocity)
-        midi_usb.send(msg_on)
-
-    Example of sending MIDI over UART (TRS or 5-pin):
-
-    .. code-block:: python
-
-        import board
-        import busio
-        import tmidi
-        uart = busio.UART(tx=board.TX, rx=board.RX, timeout=0.001)
-        midi_uart = tmidi.MIDI(midi_out=uart)
-        msg_on = tmidi.Message(tmidi.NOTE_ON, notenum, velocity)
-        midi_uart.send(msg_on)
-
-    Example of receiving MIDI:
-
-    .. code-block:: python
-
-        import board
-        import busio
-        import usb_midi
-        import tmidi
-        uart = busio.UART(tx=board.TX, rx=board.RX, timeout=0.001)
-        midi_uart = tmidi.MIDI(midi_in=uart, midi_out=uart)
-        midi_usb = tmidi.MIDI(midi_in=usb_midi.ports[0], midi_out=usb_midi.ports[1])
-
-        while True:
-            if msg := midi_usb.receive():
-                print("usb midi:", msg)
-            if msg := midi_uart.receive():
-                print("uart midi:", msg)
-    """
-
-    def __init__(self, midi_in=None, midi_out=None, enable_running_status=False):
-        self._in_port = midi_in
-        self._out_port = midi_out
-        self._running_status_enabled = enable_running_status
-        self._running_status = None
-        self._error_count = 0
-
-        # This input buffer holds what has been read from midi_in
-        self._read_buf = bytearray(1)
-
-    @property
-    def error_count(self):
-        """Number of errors encountered when parsing received messages"""
-        return self._error_count
-
-    def receive(self):
-        """Read message from MIDI port, parse that data and
-        return the first MIDI message (event).
-        This maintains the blocking characteristics of the midi_in port.
-        Relies on the port to buffer the incoming unread MIDI messages.
-
-        :returns Message object: Returns object or None for nothing.
-        """
-
-        # Read the status byte for the next message.
-        # note: this will block if the port is set to have a timeout
-        status_byte_buf = self._in_port.read(1)
-
-        # No message ready.
-        if not status_byte_buf:
-            return None
-
-        # Is this actually a status byte?
-        status_byte = status_byte_buf[0]
-        is_status = status_byte & 0x80
-
-        # If not, see if we have a running status byte.
-        if not is_status:
-            if self._running_status_enabled and self._running_status:
-                status_byte = self._running_status
-            # If not a status byte and no running status, this is invalid data.
-            else:
-                self._error_count += 1
-                return None
-
-        message = Message(status_byte)
-
-        # Is this a channel message, if so, let's figure out the right
-        # message type and set the message's channel property.
-        if _is_channel_message(status_byte):
-            # Only set the running status byte for channel messages.
-            self._running_status = status_byte
-            # Mask off the channel nibble.
-            message.type = status_byte & 0xF0
-            message.channel = status_byte & 0x0F
-
-        # Read the appropriate number of bytes for each message type.
-        if message.type in _LEN_2_MESSAGES:
-            message.data0 = _read_byte(self._in_port)
-            message.data1 = _read_byte(self._in_port)
-        elif message.type in _LEN_1_MESSAGES:
-            message.data0 = _read_byte(self._in_port)
-
-        # Check the data bytes for corruption. status bytes in data
-        # means we're out of sync, so discard.
-        # TODO: Figure out a better way to detect and deal with this upstream.
-        for b in (message.data0 or 0, message.data1 or 0):
-            if b & 0x80:
-                self._error_count += 1
-                return None
-
-        return message
-
-    def send(self, msg, channel=None):
-        """Send a MIDI message.
-
-        :param msg: Either a Message object or a sequence (list) of Message objects.
-            The channel property will be *updated* as a side-effect of sending message(s).
-        :param int channel: Channel number, if not set, the msg's channel will be used.
-        """
-
-        if isinstance(msg, Message):
-            if channel:
-                msg.channel = channel
-            # bytes(object) does not work in uPy
-            data = msg.__bytes__()
-        else:
-            data = bytearray()
-            for each_msg in msg:
-                if channel:
-                    each_msg.channel = channel
-                data.extend(each_msg.__bytes__())
-
-        self._out_port.write(data, len(data))