Version 12 (modified by carndt, 7 years ago) (diff)

More Changelog updates

Welcome to python-rtmidi!

A Python wrapper for the RtMidi C++ library written with Cython.

The current version is 0.3.1a, released on 2013-01-23.

svn co svn:// python-rtmidi


RtMidi is a set of C++ classes which provides a concise and simple, cross-platform API (Application Programming Interface) for realtime MIDI input/output across Linux (ALSA & JACK), Macintosh OS X (CoreMIDI & JACK), and Windows (Multimedia Library & Kernel Streaming) operating systems.

python-rtmidi is a Python binding for RtMidi implemented with Cython and provides a thin wrapper around the RtMidi C++ interface. The API is basically the same as the C++ one but with the naming scheme of classes, methods and parameters adapted to the Python PEP-8 conventions and requirements of the Python package naming structure. python-rtmidi supports Python 2 (tested with Python 2.7) and Python 3 (3.2).


python-rtmidi is currently in alpha-stage, which means is is published in the hope that other developers try it out and help finding bugs, and that its API is not yet finalised. What is there should work but is currently only tested thoroughly under Linux ALSA/JACK and less regularly under OS X (CoreMIDI/JACK) and Windows (WinMM). Support for the Windows Kernel Streaming API does not work yet due to compilation problems.

Usage example

Here's a quick example of how to use python-rtmidi to open the first available MIDI output port and send a middle C note on MIDI channel 10:

import time
import rtmidi

midiout = rtmidi.MidiOut()
available_ports = midiout.get_ports()

if available_ports:
    midiout.open_virtual_port("My virtual output")

note_on = [0x99, 60, 112] # channel 10, middle C, velocity 112
note_off = [0x89, 60, 0]

del midiout

More usage examples can be found in the tests directory of the source distribution. API documentation is available by looking at the docstrings in the Cython source code or using tools like pydoc or IPython and by reading the RtMidi documentation.


python-rtmidi is a Python C(++)-extension and therefore a C++ compiler and a build environment as well as some system-dependant libraries are needed. See "Requirements" below for details.

Installer (Windows only)

An installer with a pre-compiled version for Windows with Windows MultiMedia API support is available through PyPI for some Python versions. Download it from python-rtmidi's PyPI page and start the installer by double-clicking.

From PyPI

If you have all the dependencies, you should be able to install the package with pip or easy_install:

$ pip install python-rtmidi

or, if you prefer setuptools:

$ easy_install python-rtmidi

This will download the source distribution, compile the extension and install it in your active Python installation. Unless you want to change the Cython source file _rtmidi.pyx, there is no need to have Cython installed.

python-rtmidi also works well with virtualenv and virtualenvwrapper. If you have both installed, creating an isolated environment for testing and using python-rtmidi is as easy as:

$ mkvirtualenv rtmidi
(rtmidi)$ pip install python-rtmidi

From the Source Distribution

Of course, you can also download the source distribution package as a Zip archive or tarball, extract it and install using the common distutils commands, e.g.:

$ wget
$ tar xzf python-rtmidi-0.3a.tar.gz
$ cd python-rtmidi-0.3a
$ python install

From Subversion

Lastly, you can check out the python-rtmidi source code from the Subversion repository and then install it from your working copy. Since the repository does not include the C++ module source code pre-compiled from the Cython source, you'll also need to install Cython from its Git repository. Using virtualenv/virtualenvwrapper is strongly recommended in this scenario:

$ mkvirtualenv rtmidi
(rtmidi)$ cdvirtualenv
(rtmidi)$ git clone
(rtmidi)$ svn co svn:// python-rtmidi
(rtmidi)$ cd cython
(rtmidi)$ python install
(rtmidi)$ cd ../python-rtmidi
(rtmidi)$ python install


Naturally, you'll need a C++ compiler and a build environment. See the platform-specific hints below.

Only if you want to change the Cython source file _rtmidi.pyx or want to recompile _rtmidi.cpp with a newer Cython version, you'll need to install Cython >= 0.17. Currently this version is only available via the Git respository (see Cython web site) as version 0.17pre. The _rtmidi.cpp file in the source distribution was compiled with Cython 0.17pre as of 2013-01-14 and Python 2.7.2.

RtMidi (and therefore python-rtmidi) supports several low-level MIDI libraries on different operating systems. Only one of the available options needs to be present on the target system, but support for more than one can be compiled in. The setup script will try to detect available libraries and should use the appropriate compilations flags automatically.

  • Linux: ALSA, JACK
  • OS X: CoreMIDI, JACK
  • Windows: MultiMedia (MM), Windows Kernel Streaming


For the C++ compiler and the pthread library install the build-essential package on debian-based systems.

Then you'll need Python development headers and libraries. On Linux, install the python-dev package. If you use the official installers from you should already have these.

To get ALSA support, you must install development files for the libasound library (debian package: libasound-dev). For JACK support, install the libjack development files (libjack-dev or libjack-jackd2-dev).


Install the latest Xcode or g++ from MacPorts or homebrew (untested). CoreMIDI support comes with installing Xcode. For JACK support, install JACK for OS X with the full installer.


On Windows you'll need Visual Studio 2008 Express. Visual Studio 2010 (Express) or later editions will not work with current official Python distributions. After you have installed Visual Studio, you probably need to edit the WINLIB_DIR and WININC_DIR variables at the top of the file to point to the location of WinMM.lib and the Microsoft SDK headers.

Compiling python-rtmidi with Windows Kernel Streaming support currently does not work due to syntax errors in RtMidi.cpp. This is currently being investigated. You can exclude Windows Kernel Streaming Support by providing the --no-winks option to the invocation.

Compiling with MinGW also does not work out-of-the-box yet. If you have any useful hints, please let the author know.


For details and minor changes, please see the Subversion log messages.

Development version (unreleased)

  • midiutils.open_midiport():
    • Allow to pass (substring of) port name as alternative to port number.
    • Re-raise EOFError and KeyboardInterrupt instead of using sys.exit().
    • Add client_name and port_name arguments.
    • Add use_virtual argument (default False) to request opening of a virtual MIDI port.
    • interactive keyword argument (default True) to disable interactive prompt for port.
  • MidiIn/MidiOut and open*() methods: allow to specify None as client or port name to get the default names.
  • Add methods to OSC2MIDIHandler in osc2midi to send program changes, pitch bend, and channel and poly aftertouch; make default channel an instance variable that can be changed via OSC messages.
  • Add new oscdispatcher module to osc2midi example.
  • Lots of re-structuring and improvements to ` osc2midi``.
  • Convert osc2midi example script into a package
  • Include in source distribution.
  • Move midiconstants module from examples into rtmidi package and add midiutil module.
  • Include examples in source distribution
  • Convert / break down midifilter example script into a package.
  • Add new sysexsaver example.
  • Update version number in RtMidi.cpp/h to reflect actual code state.
  • Allow MidiIn/Out.open_port methods to be used with the with statement and the port will be closed at the end of the block.
  • Change queue_size_limit to 1024.
  • Add docstring to the rest of MidiIn methods.
  • Fix string conversion in constructors and open_* methods.
  • Change default name of virtual ports.
  • Add docstrings to many methods and functions.
  • Add new example script to demonstrate sending of control cgange messages.
  • Update from optparse to argparse in example.
  • Switch from distribute back to setuptools.
  • Add new example script to demonstrate sending of system exclusive messages.
  • Add new example script, a simple, uni-directional OSC to MIDI mapper.


2013-01-23 version 0.3.1a

  • Increase sysex input buffer size for WinMM API again to 8192 (8k) bytes. Requested by Martin Tarenskeen.

2013-01-14 version 0.3a

Bug fixes:
  • Add encoding parameter to get_port_name methods of MidiIn and MidiOut to be able to handle non-UTF-8 port names, e.g. on Windows (reported by Pierre Castellotti).
  • Add encoding parameter to get_ports method as well and pass it through to get_port_name. Use it in the test scripts.
  • Increase sysex input buffer size for WinMM API to 4096 bytes.
  • Add new example script.
  • Add setuptools/distribute support.

2012-07-22 version 0.2a

Bug fixes:
  • Fix uninitialized pointer bug in RtMidi.cpp in 'MidiOutJack' class, which caused warning in jack process callback when creating a 'MidiOut' instance with JACK API.
  • testmidiin_*.py: fix superfluous decoding of port name (caused error with Python 3)
  • Simplify some code, some things gleaned from rtmidi_python
  • Documentation typo fixes and more information on Windows compilation
  • Enhancements in test scripts:
    • Catch exceptions when creating port
    • test_midiin_*.py:
      • Better error message for missing/invalid port number
      • Show how to convert event delta time into absolute time when receiving input
  • Building on OS X 10.6.9 with CoreMIDI and JACK for OS X successfully tested and test run without errors
  • WinMM support now compiles with Visual Studio 2008 Express and tests work under Windows XP SP3 32-bit:
  • Add command line option to exclude WinMM or WinKS API from compilation
  • Add missing 'extra_compile_args' to Extension keyword args in setup file
  • add 'library_dirs' to Extension keyword args in setup file
  • use '-frtti' compiler option on OS X (neccessary on 10.7?)
  • Fix file name conflict on case-insensitive file systems by prefixing 'rtmidi.{pyx,cpp}' with an underscore
  • Provide correct compiler flags for compiling with Windows MultiMedia API
  • Adapt windows library and include path for Visual Studio 2008 Express
  • add support for compiling with Windows Kernel Streaming API (does not not compile due to syntax errors in RtMidi.cpp yet)

2012-07-13 version 0.1a

First public release