Changes

(See Roadmap for future plans.)

Release History

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 arugment 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 queue_port.py 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 rtmidi_python_backend.py, 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(messages)
      MidiTrack(port.iter_pending())
      MidiTrack(msg for msg in some_generator)
      
    • Slicing a MidiTrack returns a MidiTrack. (It used to return a list.) Example:

      track[1:10]
      
  • 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: http://pythonwheels.com/

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.