Changes between Version 12 and Version 13 of python-rtmidi


Ignore:
Timestamp:
11/05/2013 04:47:31 AM (7 years ago)
Author:
carndt
Comment:

New version, restructured page and moved some content to sub-pages

Legend:

Unmodified
Added
Removed
Modified
  • python-rtmidi

    v12 v13  
    33A Python wrapper for the !RtMidi C++ library written with Cython. 
    44 
    5 The current version is '''0.3.1a''', released on 2013-01-23. 
     5The current version is '''0.4.b''', released on 2013-11-05. 
    66 
    7 == Quicklinks == 
     7== Quick links == 
    88 
    99 * [http://python.org/pypi/python-rtmidi PyPI page] 
    1010 * [http://chrisarndt.de/projects/python-rtmidi/download/ Download distribution packages] 
     11 * [[python-rtmidi/changelog | Changelog]] 
    1112 * [source:/projects/python-rtmidi/trunk Browse source code] 
    12  * Checkout code from Subversion: 
     13 * [[wiki:python-rtmidi/install | Installation]] 
     14 * [[wiki:python-rtmidi/license | License]] 
     15 
     16 
     17Check out the code from Subversion: 
    1318 
    1419{{{ 
     
    1924{{{ 
    2025#!rst 
    21 .. contents:: 
    22     :depth: 1 
    2326 
    2427Overview 
     
    3437the same as the C++ one but with the naming scheme of classes, methods and 
    3538parameters adapted to the Python PEP-8 conventions and requirements of 
    36 the Python package naming structure. ``python-rtmidi`` supports Python 2 
    37 (tested with Python 2.7) and Python 3 (3.2). 
     39the Python package naming structure. **python-rtmidi** supports Python 2 
     40(tested with Python 2.7) and Python 3 (3.3). 
    3841 
    3942.. note:: 
    40     ``python-rtmidi`` is currently in **alpha-stage**, which means is is 
     43    **python-rtmidi** is currently in **beta-stage**, which means is is 
    4144    published in the hope that other developers try it out and help finding 
    4245    bugs, and that its API is not yet finalised. What is there should work 
    4346    but is currently only tested thoroughly under Linux ALSA/JACK and less 
    44     regularly under OS X (CoreMIDI/JACK) and Windows (WinMM). Support for the 
    45     Windows Kernel Streaming API does not work yet due to compilation problems. 
     47    regularly under OS X (CoreMIDI/JACK) and Windows (WinMM). 
     48 
     49    Support for the Windows Kernel Streaming API is currently *broken* in 
     50    RtMidi. 
    4651 
    4752 
     
    4954------------- 
    5055 
    51 Here's a quick example of how to use ``python-rtmidi`` to open the first 
    52 available MIDI output port and send a middle C note on MIDI channel 10:: 
     56Here's a quick example of how to use **python-rtmidi** to open the first 
     57available MIDI output port and send a middle C note on MIDI channel 1:: 
    5358 
    5459    import time 
     
    6368        midiout.open_virtual_port("My virtual output") 
    6469 
    65     note_on = [0x99, 60, 112] # channel 10, middle C, velocity 112 
    66     note_off = [0x89, 60, 0] 
     70    note_on = [0x90, 60, 112] # channel 1, middle C, velocity 112 
     71    note_off = [0x80, 60, 0] 
    6772    midiout.send_message(note_on) 
    6873    time.sleep(0.5) 
     
    7176    del midiout 
    7277 
    73 More usage examples can be found in the ``tests`` directory of the source 
    74 distribution. API documentation is available by looking at the docstrings in 
    75 the Cython source code or using tools like ``pydoc`` or IPython_ and by 
    76 reading the RtMidi_ documentation. 
    77  
    78  
    79 Installation 
    80 ============ 
    81  
    82 ``python-rtmidi`` is a Python C(++)-extension and therefore a C++ compiler 
    83 and a build environment as well as some system-dependant libraries are needed. 
    84 See "Requirements" below for details. 
    85  
    86  
    87 Installer (Windows only) 
    88 ------------------------ 
    89  
    90 An installer with a pre-compiled version for Windows with Windows MultiMedia 
    91 API support is available through PyPI for some Python versions. Download it 
    92 from python-rtmidi's `PyPI page`_ and start the installer by double-clicking. 
    93  
    94  
    95 From PyPI 
    96 --------- 
    97  
    98 If you have all the dependencies, you should be able to install the package 
    99 with pip_ or ``easy_install``:: 
    100  
    101     $ pip install python-rtmidi 
    102  
    103 or, if you prefer setuptools_:: 
    104  
    105     $ easy_install python-rtmidi 
    106  
    107 This will download the source distribution, compile the extension and install 
    108 it in your active Python installation. Unless you want to change the Cython 
    109 source file ``_rtmidi.pyx``, there is no need to have Cython installed. 
    110  
    111 ``python-rtmidi`` also works well with virtualenv_ and virtualenvwrapper_. If 
    112 you have both installed, creating an isolated environment for testing and using 
    113 ``python-rtmidi`` is as easy as:: 
    114  
    115     $ mkvirtualenv rtmidi 
    116     (rtmidi)$ pip install python-rtmidi 
    117  
    118  
    119 From the Source Distribution 
    120 ---------------------------- 
    121  
    122 Of course, you can also download the source distribution package as a Zip 
    123 archive or tarball, extract it and install using the common ``distutils`` 
    124 commands, e.g.:: 
    125  
    126     $ wget http://chrisarndt.de/projects/python-rtmidi/download/python-rtmidi-0.3a.tar.gz 
    127     $ tar xzf python-rtmidi-0.3a.tar.gz 
    128     $ cd python-rtmidi-0.3a 
    129     $ python setup.py install 
    130  
    131  
    132 From Subversion 
    133 --------------- 
    134  
    135 Lastly, you can check out the ``python-rtmidi`` source code from the 
    136 Subversion repository and then install it from your working copy. Since the 
    137 repository does not include the C++ module source code pre-compiled from the 
    138 Cython source, you'll also need to install Cython from its Git repository. 
    139 Using virtualenv/virtualenvwrapper is strongly recommended in this scenario:: 
    140  
    141     $ mkvirtualenv rtmidi 
    142     (rtmidi)$ cdvirtualenv 
    143     (rtmidi)$ git clone https://github.com/cython/cython.git 
    144     (rtmidi)$ svn co svn://svn.chrisarndt.de/projects/python-rtmidi/trunk python-rtmidi 
    145     (rtmidi)$ cd cython 
    146     (rtmidi)$ python setup.py install 
    147     (rtmidi)$ cd ../python-rtmidi 
    148     (rtmidi)$ python setup.py install 
    149  
    150  
    151 Requirements 
    152 ============ 
    153  
    154 Naturally, you'll need a C++ compiler and a build environment. See the 
    155 platform-specific hints below. 
    156  
    157 Only if you want to change the Cython source file ``_rtmidi.pyx`` or want to 
    158 recompile ``_rtmidi.cpp`` with a newer Cython version, you'll need to install 
    159 Cython >= 0.17. Currently this version is only available via the Git 
    160 respository (see Cython web site) as version 0.17pre. The ``_rtmidi.cpp`` file 
    161 in the  source distribution was compiled with Cython 0.17pre as of 2013-01-14 
    162 and Python 2.7.2. 
    163  
    164 RtMidi (and therefore ``python-rtmidi``) supports several low-level MIDI 
    165 libraries on different operating systems. Only one of the available options 
    166 needs to be present on the target system, but support for more than one can be 
    167 compiled in. The setup script will try to detect available libraries and should 
    168 use the appropriate compilations flags automatically. 
    169  
    170     * Linux: ALSA, JACK 
    171     * OS X: CoreMIDI, JACK 
    172     * Windows: MultiMedia (MM), Windows Kernel Streaming 
    173  
    174  
    175 Linux 
    176 ----- 
    177  
    178 For the C++ compiler and the pthread library install the ``build-essential`` 
    179 package on debian-based systems. 
    180  
    181 Then you'll need Python development headers and libraries. On Linux, install 
    182 the ``python-dev`` package. If you use the official installers from python.org 
    183 you should already have these. 
    184  
    185 To get ALSA support, you must install development files for the ``libasound`` 
    186 library (debian package: ``libasound-dev``). For JACK support, install the 
    187 ``libjack`` development files (``libjack-dev`` or ``libjack-jackd2-dev``). 
    188  
    189  
    190 OS X 
    191 ---- 
    192  
    193 Install the latest Xcode or ``g++`` from MacPorts or homebrew (untested). 
    194 CoreMIDI support comes with installing Xcode. For JACK support, install 
    195 `JACK for OS X`_ with the full installer. 
    196  
    197  
    198 Windows 
    199 ------- 
    200  
    201 On Windows you'll need Visual Studio 2008 Express. Visual Studio 2010 (Express) 
    202 or later editions will not work with current official Python distributions. 
    203 After you have installed Visual Studio, you probably need to edit the 
    204 ``WINLIB_DIR`` and ``WININC_DIR`` variables at the top of the ``setup.py`` file 
    205 to point to the location of ``WinMM.lib`` and the Microsoft SDK headers. 
    206  
    207 Compiling ``python-rtmidi`` with Windows Kernel Streaming support currently 
    208 does not work due to syntax errors in ``RtMidi.cpp``. This is currently being 
    209 investigated. You can exclude Windows Kernel Streaming Support by providing 
    210 the ``--no-winks`` option to the ``setup.py`` invocation. 
    211  
    212 Compiling with MinGW also does not work out-of-the-box yet. If you have any 
    213 useful hints, please let the author know. 
    214  
    215  
    216 Changelog 
    217 ========= 
    218  
    219 For details and minor changes, please see the `Subversion log messages 
    220 <http://trac.chrisarndt.de/code/log/projects/python-rtmidi/trunk>`_. 
    221  
    222  
    223 Development version (unreleased) 
    224 -------------------------------- 
    225  
    226 **2013-10-15** 
    227     * `midiutils.open_midiport()`: 
    228  
    229       * Allow to pass (substring of) port name as alternative to port number. 
    230       * Re-raise ``EOFError`` and ``KeyboardInterrupt`` instead of using 
    231         ``sys.exit()``. 
    232       * Add ``client_name`` and ``port_name`` arguments. 
    233       * Add ``use_virtual`` argument (default ``False``) to request opening 
    234         of a virtual MIDI port. 
    235       * ``interactive`` keyword argument (default ``True``) to disable 
    236         interactive prompt for port. 
    237  
    238     * ``MidiIn``/``MidiOut`` and ``open*()`` methods: allow to specify ``None`` 
    239       as client or port name to get the default names. 
    240  
    241     * Add methods to ``OSC2MIDIHandler`` in ``osc2midi`` to send program 
    242       changes, pitch bend, and channel and poly aftertouch; make default 
    243       channel an instance variable that can be changed via OSC messages. 
    244  
    245 **2013-10-12** 
    246     * Add new ``oscdispatcher`` module to ``osc2midi`` example. 
    247     * Lots of re-structuring and improvements to ` osc2midi``. 
    248  
    249 **2013-10-02** 
    250     * Convert ``osc2midi`` example script into a package 
    251  
    252 **2013-10-01** 
    253     * Include ``ez_setup.py`` in source distribution. 
    254  
    255 **2013-09-30** 
    256     * Move ``midiconstants`` module from examples into ``rtmidi`` package 
    257       and add ``midiutil`` module. 
    258     * Include examples in source distribution 
    259     * Convert / break down ``midifilter`` example script into a package. 
    260     * Add new ``sysexsaver`` example. 
    261     * Update version number in ``RtMidi.cpp/h`` to reflect actual code state. 
    262  
    263 **2013-09-29** 
    264     * Allow ``MidiIn/Out.open_port`` methods to be used with the ``with`` 
    265       statement and the port will be closed at the end of the block. 
    266  
    267 **2013-09-28** 
    268     * Change ``queue_size_limit`` to 1024. 
    269     * Add docstring to the rest of ``MidiIn`` methods. 
    270  
    271 **2013-09-27** 
    272     * Fix string conversion in constructors and ``open_*`` methods. 
    273     * Change default name of virtual ports. 
    274     * Add docstrings to many methods and functions. 
    275  
    276 **2013-09-24** 
    277     * Add new example script ``wavetablemodstep.py`` to demonstrate sending 
    278       of control cgange messages. 
    279  
    280 **2013-09-12** 
    281     * Update  from ``optparse`` to ``argparse`` in ``osc2midi.py`` example. 
    282  
    283 **2013-09-11** 
    284     * Switch from distribute back to setuptools. 
    285  
    286 **2013-08-08** 
    287   * Add new example script ``sendsysex.py`` to demonstrate sending of system 
    288     exclusive messages. 
    289  
    290 **2013-02-12** 
    291   * Add new example script ``osc2midi.py``, a simple, uni-directional OSC 
    292     to MIDI mapper. 
    293  
    294  
    295 Releases 
    296 -------- 
    297  
    298 **2013-01-23 version 0.3.1a** 
    299  
    300 Enhancements: 
    301     * Increase sysex input buffer size for WinMM API again to 8192 (8k) bytes. 
    302       Requested by Martin Tarenskeen. 
    303  
    304 **2013-01-14 version 0.3a** 
    305  
    306 Bug fixes: 
    307     * Add ``encoding`` parameter to ``get_port_name`` methods of ``MidiIn`` 
    308       and ``MidiOut`` to be able to handle non-UTF-8 port names, e.g. on 
    309       Windows (reported by Pierre Castellotti). 
    310     * Add ``encoding`` parameter to ``get_ports`` method as well and pass it 
    311       through to ``get_port_name``. Use it in the test scripts. 
    312  
    313 Enhancements: 
    314     * Increase sysex input buffer size for WinMM API to 4096 bytes. 
    315  
    316 Examples: 
    317     * Add new ``midifilter.py`` example script. 
    318  
    319 Building: 
    320     * Add ``setuptools``/``distribute`` support. 
    321  
    322 **2012-07-22 version 0.2a** 
    323  
    324 Bug fixes: 
    325     * Fix uninitialized pointer bug in RtMidi.cpp in 'MidiOutJack' class, which 
    326       caused warning in jack process callback when creating a 'MidiOut' 
    327       instance with JACK API. 
    328     * ``testmidiin_*.py``: fix superfluous decoding of port name (caused error 
    329       with Python 3) 
    330  
    331 Enhancements: 
    332     * Simplify some code, some things gleaned from rtmidi_python 
    333     * Documentation typo fixes and more information on Windows compilation 
    334     * Enhancements in test scripts: 
    335  
    336       * ``test_probe_ports.py``: Catch exceptions when creating port 
    337       * ``test_midiin_*.py``: 
    338  
    339         * Better error message for missing/invalid port number 
    340         * Show how to convert event delta time into absolute time when 
    341           receiving input 
    342  
    343 Building: 
    344     * Building on OS X 10.6.9 with CoreMIDI and JACK for OS X successfully 
    345       tested and test run without errors 
    346     * WinMM support now compiles with Visual Studio 2008 Express and tests 
    347       work under Windows XP SP3 32-bit: 
    348     * Add command line option to exclude WinMM or WinKS API from compilation 
    349     * Add missing 'extra_compile_args' to Extension keyword args in setup file 
    350     * add 'library_dirs' to Extension keyword args in setup file 
    351     * use '-frtti' compiler option on OS X (neccessary on 10.7?) 
    352     * Fix file name conflict on case-insensitive file systems by prefixing 
    353       'rtmidi.{pyx,cpp}' with an underscore 
    354     * Provide correct compiler flags for compiling with Windows MultiMedia API 
    355     * Adapt windows library and include path for Visual Studio 2008 Express 
    356     * add support for compiling with Windows Kernel Streaming API (does not 
    357       not compile due to syntax errors in RtMidi.cpp yet) 
    358  
    359 **2012-07-13 version 0.1a** 
    360  
    361 First public release 
    362  
    363  
    364 Copyright & License 
    365 =================== 
    366  
    367 ``python-rtmidi`` was written by Christopher Arndt, 2012. 
    368  
    369 The author can be reached at chris@chrisarndt.de. 
    370  
    371 The software is released unter the **MIT License**: 
    372  
    373 Copyright (c) 2012 Christopher Arndt 
    374  
    375     Permission is hereby granted, free of charge, to any person obtaining a 
    376     copy of this software and associated documentation files (the "Software"), 
    377     to deal in the Software without restriction, including without limitation 
    378     the rights to use, copy, modify, merge, publish, distribute, sublicense, 
    379     and/or sell copies of the Software, and to permit persons to whom the 
    380     Software is furnished to do so, subject to the following conditions: 
    381  
    382     The above copyright notice and this permission notice shall be included 
    383     in all copies or substantial portions of the Software. 
    384  
    385     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 
    386     OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
    387     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
    388     AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
    389     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
    390     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
    391     DEALINGS IN THE SOFTWARE. 
     78More usage examples can be found in the ``tests`` and ``examples`` directory 
     79of the source distribution. API documentation is available by looking at the 
     80docstrings in the Cython source code ``src/_rtmidi.pyx`` or using tools like 
     81``pydoc`` or IPython_ and by reading the (somewhat terse and inaccurate) 
     82RtMidi_ documentation. 
    39283 
    39384 
    39485.. _rtmidi: http://www.music.mcgill.ca/~gary/rtmidi/index.html 
    395 .. _python-rtmidi: http://chrisarndt.de/projects/python-rtmidi/ 
    396 .. _pypi page: http://python.org/pypi/python-rtmidi#downloads 
    397 .. _cython: http://cython,org/ 
    398 .. _pip: http://python.org/pypi/pip 
    399 .. _setuptools: http://python.org/pypi/setuptools 
    400 .. _virtualenv: http://pypi.python.org/pypi/virtualenv 
    401 .. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper/ 
     86.. _python-rtmidi: %(url)s 
     87.. _cython: http://cython.org/ 
    40288.. _ipython: http://ipython.org/ 
    403 .. _jack for os x: http://www.jackosx.com/ 
    40489 
    40590}}} 
     91 
     92