Version Changes

This project uses Semantic Versioning.

See also

The Future milestone on Github for future plans.

Release History

1.3.2 (2023-12-15)

  • Bugfix Midifile: skip_checks were missing on MetaMessage (@almostimplemented)

  • Bugfix Scripts/mido-play: UnboundLocalError (@rdoursenaud)

  • Minor documentation cleanup (@rdoursenaud)

1.3.1 (2023-12-14)

  • New Python 3.12 support

  • Improved merged_tracks performance (@almostimplemented, pull request #474)

  • Bugfix Backends/portmidi: SysEx messages were generating an error (@tweakoz, pull request #523)

  • Bugfix Midifile: Defer computing merged_track (@akx, pull request #565)

  • Bugfix pip release: Scripts can now be executed properly (@rdoursenaud)

  • Tooling: Linting now uses ruff (@akx, pull requests #564, #566)

  • Minor documentation improvements (@rdoursenaud)

1.3.0 (2023-07-21)


This release drops support for Python 2 and is only compatible with 3.7 onwards.

  • Bugfix Backends/rtmidi: Prevent virtual port name mangling (@rdoursenaud, thanks to @digitalsignalperson for reporting)

  • Bugfix Backends/rtmidi: Remove callback before closing the port to avoid a race condition (@rdoursenaud)

  • Bugfix MidiFile: Properly decode/encode SMPTE hours in the SMPTE offset Meta (Thanks to @laori93 for reporting and @heilei for investigating. Issue #156)

  • Installation: support the “extras” syntax to install optional dependencies (@rdoursenaud)

  • Documentation: updated, overhauled and proofread (@rdoursenaud, nomadbyte, @superbock)

  • Bugfix: Backends/Portmidi (@akx, pull request #483)

  • MidiFile: Move merging track out of __iter__() to prevent hanging on first call (@Frnot, pull request #470)

  • MidiFile: play() can now use an optional custom clock source (@almostimplemented, pull request #153)

  • The project is now REUSE compliant. See for details (@rdoursenaud)

  • Packaging is now PEP-518 compliant (@rdoursenaud)

  • Backends/Socket: Disable buffering (@m-vo, pull request #342)

  • Removed support for Python 2.7. * Mido now requires Python 3.7 or higher. (Ole Martin Bjørndalen, pull request #408, with additional cleanup from @rdoursenaud)

  • Backends: The rtmidi and python-rtmidi 1.2.10 sometimes returned duplicate port names. (Bug introduced in 1.2.10. Fix by Maciej Sokołowski, pull request #321)

  • Bugfix Backends/Socket: In Python 3, PortServer used to crashe when a socket client disconnects. (issue #290) (@kyleclaassen, pull request #291)

  • MidiFile: Make UnknownMetaMessage robust to faulty MIDI files (@sonovice, pull request #286)

  • Bugfix MIDIFile: BPM <-> MIDI tempo conversions (@superbock, pull request #114)

  • MidiFile: Added from_bytes() to MetaMessage (@gulaki, pull request #149)

1.2.10 (2021-05-10)

  • New repr() format for messages, tracks and MIDI file objects. (Implemented by John Belmonte, pull request #164.)

  • added new example midifiles/ based on the new repr() format.

  • Added msg.is_cc() method. Checks if message is a control change. Can also be used to check for a specific control change number, for example msg.is_cc(7).

  • Fixed memory leaks in RtMidi backend (issue #256, fix by The Other Days, pull request #264.)

  • clip now works with sysex messages (Fix by Avatar Timo Stüber, pull request #229.)

  • Improved docs and error message for time attribute in a message. (tomerv, pull request #249.)

  • Improved to avoid time drift. (Implemented by John Belmonte, pull request #161.)

  • bugfix: MIDO_DEFAULT_INPUT was misspelled in mido-ports causing it to be show as ‘not set’ even though it was set. (Fix by Bernhard Wagner, pull request #192.)

  • Now only copies ports once in ports.multi_receive() (Tom Ritchford, pull request #191.)

  • Ports lists returned from get_input_names() and friends are no longer sorted. (Suggested and implemented by Ryan McCampbell, issue #298.)

  • Updated linke in docs to point to the new home (Fixed by Joshua Mayers, pull request #177.)

  • thanks to Christopher Arndt, Kathryn DiPippo and Timo Stüber for fixing flake8 issues.

1.2.9 (2018-10-05)

  • rewrote Parser class around a MIDI tokenizer. Should lead to slight speedup and much cleaner code.

  • bugfix: data attribute was missing for UnknownMetaMessage objects. This caused AttributeError when the messages were printed or saved to a file. Also, the documentation incorrectly listed the attribute as _data instead of data. (Reported by Groowy.)

  • bugfix: UnknownMetaMessage encoding was broken causing crashes when saving a file with unknown meta messages. (Reported by exeex, issue #159.)

  • bugfix: inputs and outputs were switched around when opening named ports with PortMidi backend. (Reproduced by Predrag Radovic, issue #108, fix by Juan Antonio Aldea, pull request #109.)

  • bugfix: time signature meta messages had wrong default value of 2/4. The default value is now 4/4. (Fix by Sebastian Böck, pull request #104.)

  • bugfix: msg.copy() didn’t handle generators for sysex data. msg.copy(data=(i for i in range(3))) would give data=() instead of data=(0,1,2).

    (The code should be refactored so this is handled by the same function everywhere, such as in __init__(), in copy() and in parser.feed().)

  • bugfix: MultiPort._receive() ignored the block parameter. (Fix by Tom Swirly, pull request #135.)

  • bugfix: sequencer number meta message was incorrectly limited to range 0..255 instead of 0..65335. (Reported by muranyia, issue #144.)

  • now using Tox for testing. (Implemented by Chris Apple, pull request #123.)

  • Travis integration up by Carl Thomé and Chris Apple.

1.2.8 (2017-06-30)

  • bugfix: nonblocking receive was broken for RtMidi IO ports. (Reported by Chris Apple, issue #99.)

  • bugfix: IOPort.poll() would block if another thread was waiting for receive(). Fixed the problem by removing the lock, which was never needed in the first place as the embedded input port does its own locking.

1.2.7 (2017-05-31)

  • added max length when reading message from a MIDI file. This prevents Python from running out of memory when reading a corrupt file. Instead it will now raise an IOError with a descriptive error message. (Implemented by Curtis Hawthorne, pull request #95.)

  • removed dependency on python-rtmidi from tests. (Reported by Josue Ortega, issue #96.)

1.2.6 (2017-05-04)

  • bugfix: Sending sysex with Pygame in Python 3 failed with "TypeError: array() argument 1 must be a unicode character, not byte". (Reported by Harry Williamson.)

  • now handles sequence_number and midi_port messages with 0 data bytes. These are incorrect but can occur in rare cases. See mido/midifiles/ for more. (Reported by Gilthans (issue #42) and hyst329 (issue #93)).

1.2.5 (2017-04-28)

  • bugfix: RtMidi backend ignored api argument. (Fix by Tom Feist, pull request #91.)

1.2.4 (2017-03-19)

  • fixed outdated python-rtmidi install instructions. (Reported by Christopher Arndt, issue #87.)

1.2.3 (2017-03-14)

  • typo and incorrect links in docs fixed by Michael (miketwo) (pull requests #84 and #85).

1.2.2 (2017-03-14)

  • bugfix: sysex data was broken in string format encoding and decoding. The data was encoded with spaces (‘data=(1, 2, 3)’) instead of as one word (‘data=(1,2,3)’).

  • added some tests for string format.

  • bugfix: BaseOutput.send() raised string instead of ValueError.

1.2.1 (2017-03-10)

  • bugfix: IO port never received anything when used with RtMidi backend. (Reported by dagargo, issue #83.)

    This was caused by a very old bug introduced in 1.0.3. IOPort mistakenly called the inner method self.input._receive() instead of self.input.receive(). This happens to work for ports that override _receive() but not for the new RtMidi backend which overrides receive(). (The default implementation of _receive() just drops the message on the floor.)

  • bugfix: PortMidi backend was broken due to missing import (ctypes.byref). (Introduced in 1.2.0.)

1.2.0 (2017-03-07)

New implementation of messages and parser:

  • completely reimplemented messages. The code is now much simpler, clearer and easier to work with.

  • new contructors Message.from_bytes(), Message.from_hex(), Message.from_str().

  • new message attributes is_meta and is_realtime.

Frozen (immutable) messages:

  • added FrozenMessage and FrozenMetaMessage. These are immutable versions of Message and MetaMessage that are hashable and thus can be used as dictionary keys. These are available in mido.frozen. (Requested by Jasper Lyons, issue #36.)

RtMidi is now the default backend:

  • switched default backend from PortMidi to RtMidi. RtMidi is easier to install on most systems and better in every way.

    If you want to stick to PortMidi you can either set the environment variable $MIDO_BACKEND=mido.backends.portmidi or call mido.set_backend('mido.backends.portmidi') in your program.

  • refactored the RtMidi backend to have a single Port class instead of inheriting from base ports. It was getting hard to keep track of it all. The code is now a lot easier to reason about.

  • you can now pass client_name when opening RtMidi ports: open_output('Test', client_name='My Client'). When client_name is passed the port will automatically be a virtual port.

  • with LINUX_ALSA you can now omit client name and ALSA client/port number when opening ports, allowing you to do mido.open_output('TiMidity port 0') instead of mido.open_output('TiMidity:TiMidity port 0 128:0'). (See RtMidi backend docs for more.)

Changes to the port API:

  • ports now have is_input and is_output attributes.

  • new functions tick2second() and second2tick(). (By Carl Thomé, pull request #71.)

  • added _locking attribute to BasePort. You can set this to False in a subclass to do your own locking.

  • _receive() is now allowed to return a messages. This makes the API more consistent and makes it easier to implement thread safe ports.

  • pending() is gone. This had to be done to allow for the new _receive() behavior.

  • improved MIDI file documentation. (Written by Carl Thomé.)

Other changes:

  • bugfix: if a port inherited from both BaseInput and BaseOutput this would cause BasePort.__init__() to be called twice, which means self._open() was also called twice. As a workaround BasePort.__init__() will check if self.closed exists.

  • added mido.version_info.

  • mido.set_backend() can now be called with load=True.

  • added multi_send().

  • MIN_PITCHWHEEL, MAX_PITCHWHEEL, MIN_SONGPOS and MAX_SONGPOS are now available in the top level module (for example mido.MIN_PITCHWHEEL).

  • added experimental new backend mido.backends.amidi. This uses the ALSA amidi command to send and receive messages, which makes it very inefficient but possibly useful for sysex transfer.

  • added new backend mido.backends.rtmidi_python (previously available in the examples folder.) This uses the rtmidi-python package instead of python-rtmidi. For now it lacks some of features of the rtmidi backend, but can still be useful on systems where python-rtmidi is not available. (Requested by netchose, issue #55.)

1.1.24 (2017-02-16)

  • bugfix: PortMidi backend was broken on macOS due to a typo. (Fix by Sylvain Le Groux, pull request #81.)

1.1.23 (2017-01-31)

  • bugfix: read_syx_file() didn’t handle ‘n’ in text format file causing it to crash. (Reported by Paul Forgey, issue #80.)

1.1.22 (2017-01-27)

  • the bugfix in 1.1.20 broke blocking receive() for RtMidi. Reverting the changes. This will need some more investigation.

1.1.21 (2017-01-26)

  • bugfix: MidiFile save was broken in 1.1.20 due to a missing import.

1.1.20 (2017-01-26)

  • bugfix: close() would sometimes hang for RtMidi input ports. (The bug was introduced in 1.1.18 when the backend was rewritten to support true blocking.)

  • Numpy numbers can now be used for all message attributes. (Based on implementation by Henry Mao, pull request #78.)

    The code checks against numbers.Integral and numbers.Real (for the time attribute) so values can be any subclass of these.

1.1.19 (2017-01-25)

  • Pygame backend can now receive sysex messages. (Fix by Box of Stops.)

  • bugfix: libportmidi.dylib was not found when using MacPorts. (Fix by yam655, issue #77.)

  • bugfix: SocketPort.__init() was not calling IOPort.__init__() which means it didn’t get a self._lock. (Fixed by K Lars Lohn, pull request #72. Also reported by John J. Foerch, issue #79.)

  • fixed typo in intro example (README and index.rst). Fix by Antonio Ospite (pull request #70), James McDermott (pull request #73) and Zdravko Bozakov (pull request #74).

  • fixed typo in virtual ports example (Zdravko Bozakov, pull request #75.)

1.1.18 (2016-10-22)

  • time is included in message comparison. msg1 == msg2 will now give the same result as str(msg1) == str(msg2) and repr(msg1) == repr(msg2).

    This means you can now compare tracks wihout any trickery, for example: mid1.tracks == mid2.tracks.

    If you need to leave out time the easiest was is msg1.bytes() == msg2.bytes().

    This may in rare cases break code.

  • bugfix: end_of_track messages in MIDI files were not handled correctly. (Reported by Colin Raffel, issue #62).

  • bugfix: merge_tracks() dropped messages after the first end_of_track message. The new implementation removes all end_of_track messages and adds one at the end, making sure to adjust the delta times of the remaining messages.

  • refactored MIDI file code.

  • mido-play now has a new option -m / --print-messages which prints messages as they are played back.

  • renamed parser._parsed_messages to parser.messages. BaseInput and SocketPort use it so it should be public.

  • Parser() now takes an option argument data which is passed to feed().

1.1.17 (2016-10-06)

  • RtMidi now supports true blocking receive() in Python 3. This should result in better performance and lower latency. (Thanks to Adam Roberts for helping research queue behavior. See issue #49 for more.)

  • bugfix: MidiTrack.copy() (Python 3 only) returned list.

  • fixed example which broke when locks where added.

1.1.16 (2016-09-27)

  • bugfix: MidiTrack crashed instead of returning a message on track[index]. Fix by Colin Raffel (pull request #61).

  • added __add__() and __mul__() to MidiTrack so + and * will return tracks instead of lists.

  • added poll() method to input ports as a shortcut for receive(block=False).

  • added example, a backend for the rtmidi-python package (which is different from the python-rtmidi backend that Mido currently uses.) This may at some point be added to the package but for now it’s in the examples folder. (Requested by netchose, issue #55.)

  • removed custom _import_module(). Its only function was to make import errors more informative by showing the full module path, such as ImportError: mido.backends.rtmidi instead of just ImportError: rtmidi. Unfortunately it ended up masking import errors in the backend module, causing confusion.

    It turns importlib.import_module() can be called with the full path, and on Python 3 it will also display the full path in the ImportError message.

1.1.15 (2016-08-24)

  • Sending and receiving messages is now thread safe. (Initial implementation by Adam Roberts.)

  • Bugfix: PortServer called __init__ from the wrong class. (Fix by Nathan Hurst.)

  • Changes to MidiTrack:

    • MidiTrack() now takes a as a parameter an iterable of messages. Examples:

      MidiTrack(msg for msg in some_generator)
    • Slicing a MidiTrack returns a MidiTrack. (It used to return a list.) Example:

  • Added the ability to use file objects as well as filenames when reading, writing and saving MIDI files. This allows you to create a MIDI file dynamically, possibly not using mido, save it to an io.BytesIO, and then play that in-memory file, without having to create an intermediate external file. Of course the memory file (and/or the MidiFile) can still be saved to an external file. (Implemented by Brian O’Neill.)

  • PortMidi backend now uses pm.lib.Pm_GetHostErrorText() to get host error messages instead of just the generic “PortMidi: `Host error'”. (Implemented by Tom Manderson.)

Thanks to Richard Vogl and Tim Cook for reporting errors in the docs.

1.1.14 (2015-06-09)

  • bugfix: merge_tracks() concatenated the tracks instead of merging them. This caused tracks to be played back one by one. (Issue #28, reported by Charles Gillingham.)

  • added support for running status when writing MIDI files. (Implemented by John Benediktsson.)

  • rewrote the callback system in response to issues #23 and #25.

  • there was no way to set a callback function if the port was opened without one. (Issue#25, reported by Nils Werner.)

    Callbacks can now be set and cleared at any time by either passing one to open_input() or updating the callback attribute.

    This causes some slight changes to the behavior of the port when using callbacks. Previously if you opened the port with a callback and then set port.callback = None the callback thread would keep running but drop any incoming messages. If you do the same now the callback thread will stop and the port will return normal non-callback behavior. If you want the callback thread to drop messages you can set port.callback = lambda message: None.

    Also, receive() no longer checks self.callback. This was inconsistent as it was the only method to do so. It also allows ports that don’t support callbacks to omit the callback attribute.

  • bugfix: closing a port would sometimes cause a segfault when using callbacks. (Issue #24, reported by Francesco Ceruti.)

  • bugfix: Pygame ports were broken due to a faulty check for virtual=True.

  • now raises ValueError instead of IOError if you pass virtual or callback while opening a port and the backend doesn’t support them. (An unsupported argument is not an IO error.)

  • fixed some errors in backend documentation. (Pull request #23 by velolala.)

  • MultiPort now has a yield_port argument just like multi_receive().

1.1.13 (2015-02-07)

  • the PortMidi backend will now return refresh the port list when you ask for port names are open a new port, which means you will see devices that you plug in after loading the backend. (Due to limitations in PortMidi the list will only be refreshed if there are no open ports.)

  • bugfix: tempo2bpm() was broken and returned the wrong value for anything but 500000 microseconds per beat (120 BPM). (Reported and fixed by Jorge Herrera, issue #21)

  • bugfix: merge_tracks() didn’t work with empty list of tracks.

  • added proper keyword arguments and doc strings to open functions.

1.1.12 (2014-12-02)

  • raises IOError if you try to open a virtual port with PortMidi or Pygame. (They are not supported by these backends.)

  • added merge_tracks().

  • removed undocumented method MidiFile.get_messages(). (Replaced by merge_tracks(mid.tracks).)

  • bugfix: receive() checked self.callback which didn’t exist for all ports, causing an AttributeError.

1.1.11 (2014-10-15)

  • added bpm2tempo() and tempo2bpm().

  • fixed error in documentation (patch by Michael Silver).

  • added notes about channel numbers to documentation (reported by ludwig404 / leonh, issue #18).

1.1.10 (2014-10-09)

  • bugfix: MidiFile.length was computer incorrectly.

  • bugfix: tempo changes caused timing problems in MIDI file playback. (Reported by Michelle Thompson.)

  • mido-ports now prints port names in single ticks.

  • MidiFile.__iter__() now yields end_of_track. This means playback will end there instead of at the preceding message.

1.1.9 (2014-10-06)

  • bugfix: _compute_tick_time() was not renamed to _compute_seconds_per_tick() everywhere.

  • bugfix: sleep time in play() was sometimes negative.

1.1.8 (2014-09-29)

  • bugfix: timing in MIDI playback was broken from 1.1.7 on. Current time was subtracted before time stamps were converted from ticks to seconds, leading to absurdly large delta times. (Reported by Michelle Thompson.)

  • bugfix: read_syx_file() didn’t handle empty file.

1.1.7 (2014-08-12)

  • some classes and functions have been moved to more accessible locations:

    from mido import MidiFile, MidiTrack, MetaMessage
    from mido.midifiles import MetaSpec, add_meta_spec
  • you can now iterate over a MIDI file. This will generate all MIDI messages in playback order. The time attribute of each message is the number of seconds since the last message or the start of the file. (Based on suggestion by trushkin in issue #16.)

  • added get_sleep_time() to complement set_sleep_time().

  • the Backend object no longer looks for the backend module exists on startup, but will instead just import the module when you call one of the open_*() or get_*() functions. This test didn’t work when the library was packaged in a zip file or executable.

    This means that Mido can now be installed as Python egg and frozen with tools like PyInstaller and py2exe. See “Freezing Mido Programs” for more on this.

    (Issue #17 reported by edauenhauer and issue #14 reported by netchose.)

  • switched to pytest for unit tests.

1.1.6 (2014-06-21)

  • bugfix: package didn’t work with easy_install. (Issue #14, reported by netchose.)

  • bugfix: 100% memory consumption when calling blocking receive() on a PortMidi input. (Issue #15, reported by Francesco Ceruti.)

  • added wheel support:

1.1.5 (2014-04-18)

  • removed the ‘mode’ attribute from key_signature messages. Minor keys now have an ‘m’ appended, for example ‘Cm’.

  • bugfix: sysex was broken in MIDI files.

  • bugfix: didn’t handle MIDI files without track headers.

  • bugfix: MIDI files didn’t handle channel prefix > 15

  • bugfix: MIDI files didn’t handle SMPTE offset with frames > 29

1.1.4 (2014-10-04)

  • bugfix: files with key signatures Cb, Db and Gb failed due to faulty error handling.

  • bugfix: when reading some MIDI files Mido crashed with the message “ValueError: attribute must be in range 0..255”. The reason was that Meta messages set running status, which caused the next statusless message to be falsely interpreted as a meta message. (Reported by Domino Marama).

  • fixed a typo in MidiFile._read_track(). Sysex continuation should work now.

  • rewrote tests to make them more readable.

1.1.3 (2013-10-14)

  • messages are now copied on send. This allows the sender to modify the message and send it to another port while the two ports receive their own personal copies that they can modify without any side effects.

1.1.2 (2013-10-05)

  • bugfix: non-ASCII character caused trouble with installation when LC_ALL=C. (Reported by Gene De Lisa)

  • bugfix: used old exception handling syntax in rtmidi backend which broke in 3.3

  • fixed broken link in

1.1.1 (2013-10-04)

  • bugfix: mido.backends package was not included in distribution.

1.1.0 (2013-10-01)

  • added support for selectable backends (with MIDO_BACKEND) and included python-rtmidi and pygame backends in the official library (as mido.backend.rtmidi and mido.backend.pygame).

  • added full support for MIDI files (read, write playback)

  • added MIDI over TCP/IP (socket ports)

  • added utility programs mido-play, mido-ports, mido-serve and mido-forward.

  • added support for SMPTE time code quarter frames.

  • port constructors and open_*() functions can now take keyword arguments.

  • output ports now have reset() and panic() methods.

  • new environment variables MIDO_DEFAULT_INPUT, MIDO_DEFAULT_OUTPUT and MIDO_DEFAULT_IOPORT. If these are set, the open_*() functions will use them instead of the backend’s default ports.

  • added new meta ports MultiPort and EchoPort.

  • added new examples and updated the old ones.

  • format_as_string() now takes an include_time argument (defaults to True) so you can leave out the time attribute.

  • sleep time inside sockets can now be changed.

  • Message() no longer accepts a status byte as its first argument. (This was only meant to be used internally.)

  • added callbacks for input ports (PortMidi and python-rtmidi)

  • PortMidi and pygame input ports now actually block on the device instead of polling and waiting.

  • removed commas from repr() format of Message and MetaMessage to make them more consistent with other classes.

1.0.4 (2013-08-15)

  • rewrote parser

1.0.3 (2013-07-12)

  • bugfix: __exit__() didn’t close port.

  • changed repr format of message to start with “message”.

  • removed support for undefined messages. (0xf4, 0xf5, 0xf7, 0xf9 and 0xfd.)

  • default value of velocity is now 64 (0x40). (This is the recommended default for devices that don’t support velocity.)

1.0.2 (2013-07-31)

  • fixed some errors in the documentation.

1.0.1 (2013-07-31)

  • multi_receive() and multi_iter_pending() had wrong implementation. They were supposed to yield only messages by default.

1.0.0 (2013-07-20)

Initial release.

Basic functionality: messages, ports and parser.