mido-1.1.18/0000775000175000017500000000000013002711364012747 5ustar olembolemb00000000000000mido-1.1.18/setup.py0000775000175000017500000000247612775440355014514 0ustar olembolemb00000000000000#!/usr/bin/env python import os import sys import mido try: from setuptools import setup except ImportError: from distutils.core import setup if sys.argv[-1] == "publish": os.system("python setup.py sdist upload") sys.exit() elif sys.argv[-1] == "test": os.system("./run_tests.py") sys.exit() elif sys.argv[-1] == "docs": os.system("sphinx-build docs docs/_build") sys.exit() setup( name='mido', version=mido.__version__, description='MIDI Objects for Python', long_description=open('README.rst', 'rt').read(), author=mido.__author__, author_email=mido.__email__, url=mido.__url__, package_data={'': ['LICENSE']}, package_dir={'mido': 'mido'}, packages = ['mido', 'mido.backends'], scripts = ['bin/mido-play', 'bin/mido-ports', 'bin/mido-serve', 'bin/mido-connect'], include_package_data=True, install_requires=[], license='MIT', zip_safe=False, classifiers=( 'Development Status :: 5 - Production/Stable', 'Intended Audience :: Developers', 'Natural Language :: English', 'License :: OSI Approved :: MIT License', 'Programming Language :: Python', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3.2', ), ) mido-1.1.18/docs/0000775000175000017500000000000013002711364013677 5ustar olembolemb00000000000000mido-1.1.18/docs/_static/0000775000175000017500000000000013002711364015325 5ustar olembolemb00000000000000mido-1.1.18/docs/_static/PLACEHOLDER0000664000175000017500000000007012775440355017006 0ustar olembolemb00000000000000This file is needed for git to include this directory. mido-1.1.18/docs/implementing_ports.rst0000664000175000017500000001254113002711347020354 0ustar olembolemb00000000000000Writing a New Port ================== The Mido port API allows you to write new ports to do practically anything. A new port type can be defined by subclassing one of the base classes and overriding one or more methods. Here's an example:: from mido.ports import BaseOutput class PrintPort(BaseOutput): def _send(message): print(message) >>> port = PrintPort() >>> port.send(msg) note_on channel=0 note=0 velocity=64 time=0 ``_send()`` will be called by ``send()``, and is responsible for actually sending the message somewhere (or in this case print it out). Overridable Methods ------------------- There are four overridable methods (all of them default to doing nothing):: ``_open(self, **kwargs)`` Should do whatever is necessary to initialize the port (for example opening a MIDI device.) Called by ``__init__()``. The ``name`` attribute is already set when ``_open()`` is called, but you will get the rest of the keyword arguments. If your port takes a different set of arguments or has other special needs, you can override ``__init__()`` instead. ``_close(self)`` Should clean up whatever resources the port has allocated (such as closing a MIDI device). Called by ``close()`` if the port is not already closed. ``_send(self, message)`` (Output ports only.) Should send the message (or do whatever else that makes sense). Called by ``send()`` if the port is open and the message is a Mido message. (You don't need any type checking here.) Raise IOError if something goes wrong. ``_receive(self, block=True)`` (Input ports only.) Should poll the device for available data and feed it to the parser. Should not return anything. The caller will take care of this, and anything you return here will be ignored. Is called by various input port methods, like ``receive()`` and ``pending()``. The caller takes care of blocking and various error situations, so all you need to do is to feed data into the parser. If ``block == True`` and the device supports blocking reads, you can loop and read until there is a message in ``_messages``. See the seconds example below. Raise IOError if something goes wrong. Each method corresponds to the public method of the same name, and will be called by that method. The outer method will take care of many things, so the inner method only needs to do the very minimum. The outer method also provides the doc string, so you don't have to worry about that. The base classes are ``BaseInput``, ``BaseOutput`` and ``BaseIOPort`` (which is a subclass of the other two.) Examples -------- An full example of a device port for the imaginary MIDI library ``fjopp``:: import fjopp from mido.ports import BaseIOPort # This defines an I/O port. class FjoppPort(BaseIOPort): def _open(self, **kwargs): self._device = fjopp.open_device(self.name) def _close(self): self._device.close() def _send(self, message): self.device.write(message.bytes()) def _receive(self, block=True): while True: data = self.device.read() if data: self._parser.feed(data) else: return If ``fjopp`` supports blocking read, you can do this to actually block on the device instead of letting ``receive()`` and friends poll and wait for you:: def _receive(self, block=True): if block: # Actually block on the device. # (``read_blocking()`` will always return some data.) while not ``self._messages``: data = self._device.read_blocking() self._parser.feed(data) else: # Non-blocking read like above. while True: data = self.device.read() if data: self._parser.feed(data) This can be used for any kind of port that wants to block on a pipe, an socket or another input source. Note that Mido will still use polling and waiting when receiving from multiple ports (for example in a ``MultiPort``). If you want separate input and output classes, but the ``_open()`` and ``_close()`` methods have a lot in common, you can implement this using a mix-in. Sometimes it's useful to know inside the methods whether the port supports input or output. The way to do this is to check for the methods ```send()`` and ``receive()``, for example:: def _open(self, **kwargs): if hasattr(self, 'send'): # This is an output port. if hasattr(self, 'receive'): # This is an input port. if hasattr(self, 'send') and hasattr(self, 'receive'): # This is an I/O port. Attributes ---------- A port has some attributes that can be useful inside your methods. ``name`` The name of the port. The value is device specific and does not have to be unique. It can have any value, but must be a string or ``None``. This is set by ``__init__()``. ``closed`` True if the port is closed. You don't have to worry about this inside your methods. ``_messages`` This is a ``collections.deque`` of messages that have been read and are ready to be received. This is a shortcut to ``_parser.messages``. ``_device_type`` (Optional.) If this attribute exists, it's a string which will be used in ``__repr__()``. If it doesn't exist, the class name will be used instead. mido-1.1.18/docs/ports.rst0000664000175000017500000001620013002656226015604 0ustar olembolemb00000000000000Ports ===== A Mido port is an object that can send or receive messages (or both). You can open a port by calling one of the open methods, for example:: >>> inport = mido.open_input('SH-201') >>> outport = mido.open_output('Integra-7') Now you can receive messages on the input port and send messages on the output port:: >>> msg = inport.receive() >>> outport.send(msg) The message is copied by ``send()``, so you can safely modify your original message without causing breakage in other parts of the system. In this case, the ports are device ports, and are connected to some sort of (physical or virtual) MIDI device, but a port can be anything. For example, you can use a ``MultiPort`` receive messages from multiple ports as if they were one:: from mido.ports import MultiPort ... multi = MultiPort([inport1, inport2, inport3]) for msg in multi: print(msg) This will receive messages from all ports and print them out. Another example is a socket port, which is a wrapper around a TCP/IP socket. No matter how the port is implemented internally or what it does, it will look and behave like any other Mido port, so all kinds of ports can be used interchangeably. .. note:: Sending and receiving messages is thread safe. Opening and closing ports and listing port names are not. Common Things ------------- How to open a port depends on the port type. Device ports (PortMidi, RtMidi and others defined in backends) are opened with the open functions, for example:: port = mido.open_output() Input and I/O ports (which support both input and output) are opened with ``open_input()`` and ``open_ioport()`` respectively. If you call these without a port name like above, you will get the (system specific) default port. You can override this by setting the ``MIDO_DEFAULT_OUTPUT`` etc. environment variables. To get a list of available ports, you can do:: >>> mido.get_output_names() ['SH-201', 'Integra-7'] and then:: >>> port = mido.open_output('Integra-7') There are corresponding function for input and I/O ports. To learn how to open other kinds of ports, see the documentation for the port type in question. The port name is available in ``port.name``. To close a port, call:: port.close() or use the ``with`` statement to have the port closed automatically:: with mido.open_input() as port: for message in port: do_something_with(message) You can check if the port is closed with:: if port.closed: print("Yup, it's closed.") If the port is already closed, calling ``close()`` will simply do nothing. Output Ports ------------ Output ports basically have only one method:: outport.send(message) This will send the message immediately. (Well, the port can choose to do whatever it wants with the message, but at least it's sent.) There are also a couple of utility methods:: outport.reset() This will send "all notes off" and "reset all controllers" on every channel. This is used to reset everything to the default state, for example after playing back a song or messing around with controllers. If you pass ``autoreset=True`` to the constructor, ``reset()`` will be called when the port closes:: with mido.open_output('Integra-7') as outport: for msg in inport: outport.send(msg) # reset() is called here outport.close() # or here Sometimes notes hang because a ``note_off`` has not been sent. To (abruptly) stop all sounding notes, you can call:: outport.panic() This will not reset controllers. Unlike ``reset()``, the notes will not be turned off gracefully, but will stop immediately with no regard to decay time. Input Ports ----------- To iterate over incoming messages::: for msg in port: print(msg) This will iterate over messages as they arrive on the port until the port closes. (So far only socket ports actually close by themselves. This happens if the other end disconnects.) You can also do non-blocking iteration:: for msg in port.iter_pending(): print(msg) This will iterate over all messages that have already arrived. It is typically used in main loops where you want to do something else while you wait for messages:: while True: for msg in port.iter_pending(): print(msg) do_other_stuff() In an event based system like a GUI where you don't write the main loop you can install a handler that's called periodically. Here's an example for GTK:: def callback(self): for msg in self.inport: print(msg) gobject.timeout_add_seconds(timeout, callback) To get a bit more control you can receive messagas one at a time:: msg = port.receive() This will block until a message arrives. To get a message only if one is available, you can use `poll()`:: msg = port.poll() This will return ``None`` if no message is available. .. note:: For historical reasons there's also a ``pending()`` method. It is no longer useful after ``iter_pending()`` and ``poll()`` were added but is kept around for backward compatibility. Callbacks --------- Instead of reading from the port you can install a callback function which will be called for every message that arrives. Here's a simple callback function:: def print_message(message): print(message) To install the callback you can either pass it when you create the port or later by setting the ``callback`` attribute:: port = mido.open_input(callback=print_message) port.callback = print_message ... port.callback = another_function .. note:: Since the callback runs in a different thread you may need to use locks or other synchronization mechanisms to keep your main program and the callback from stepping on each other's toes. Calling ``receive()``, ``__iter__()``, ``pending()`` or ``iter_pending()`` on a port with a callback will raise an exception:: ValueError: a callback is set for this port To clear the callback:: port.callback = None This will return the port to normal. Port API -------- Common Methods and Attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``close()`` Close the port. If the port is already closed this will simply do nothing. ``name`` Name of the port or None. ``closed`` True if the port is closed. Output Port Methods ^^^^^^^^^^^^^^^^^^^ ``send(message)`` Send a message. ``reset()`` Sends "all notes off" and "reset all controllers on all channels. ``panic()`` Sends "all sounds off" on all channels. This will abruptly end all sounding notes. Input Port Methods ^^^^^^^^^^^^^^^^^^ ``receive(block=True)`` Receive a message. This will block until it returns a message. If ``block=True`` is passed it will instead return ``None`` if there is no message. ``poll()`` Returns a message, or ``None`` if there are no pending messages. ``pending()`` Returns the number of messages waiting to be received. .. note:: This is kept around for backward compatibility. It’s better to use iter_pending() to iterate over pending messages. ``iter_pending()`` Iterates through pending messages. ``__iter__()`` Iterates through messages as they arrive on the port until the port closes. mido-1.1.18/docs/backends.rst0000664000175000017500000001037313002656226016214 0ustar olembolemb00000000000000Backends ======== Choosing Backend ---------------- Mido comes with backends for PortMidi, RtMidi and Pygame. RtMidi is the recommended backends. It has all the features of the other ones and more and is usually easier to install. For historical reasons PortMidi is still the default. You can override this with the ``MIDO_BACKEND`` environment variable, for example:: $ MIDO_BACKEND=mido.backends.rtmidi ./program.py Alternatively, you can set the backend from within your program:: >>> mido.set_backend('mido.backends.rtmidi') >>> mido.backend This will override the environment variable. If you want to use more than one backend at a time, you can do:: rtmidi = mido.Backend('mido.backends.rtmidi') portmidi = mido.Backend('mido.backends.portmidi') input = rtmidi.open_input() output = portmidi.open_output() for message in input: output.send(message) The backend will not be loaded until you call one of the ``open_`` or ``get_`` methods. You can pass ``load=True`` to have it loaded right away. If you pass ``use_environ=True`` the module will use the environment variables ``MIDO_DEFAULT_INPUT`` etc. for default ports. Environment Variables --------------------- You can override the backend's choice of default ports with these three environment variables:: MIDO_DEFAULT_INPUT MIDO_DEFAULT_OUTPUT MIDO_DEFAULT_IOPORT For example:: $ MIDO_DEFAULT_INPUT='SH-201' python program.py or:: $ export MIDO_DEFAULT_OUTPUT='Integra-7' $ python program1.py $ python program2.py RtMidi (Recommended) -------------------- Name: ``mido.backends.rtmidi`` The RtMidi backend is a thin wrapper around `python-rtmidi `_ Supports true blocking `receive()` in Python 3 which should be more efficient and result in lower latency. Sends but doesn't receive active sensing. Callbacks use RtMidi's own mechanism. RtMidi is the only backend that can create virtual ports:: >>> port = mido.open_input('New Port', virtual=True) >>> port Other applications can now connect to this port. (One oddity is that, at least in Linux, RtMidi can't see its own virtual ports, while PortMidi can see them.) The RtMidi library can be compiled with support for more than one API. You can select API by adding it after the module name, either in the environment variable:: $ export MIDO_BACKEND=mido.backends.rtmidi/LINUX_ALSA $ export MIDO_BACKEND=mido.backends.rtmidi/UNIX_JACK or in one of these:: >>> mido.set_backend('mido.backends.rtmidi/LINUX_ALSA') >>> mido.backend >>> mido.Backend('mido.backends.rtmidi/UNIX_JACK') This allows you to, for example, use both ALSA and JACK ports in the same program. To get a list of available APIs:: >>> mido.backend.module.get_api_names() ['LINUX_ALSA', 'UNIX_JACK'] There are a couple of problems with port names in Linux. First, RtMidi can't see some software ports such as ``amSynth MIDI IN``. PortMidi uses the same ALSA sequencer API, so this is problem in RtMidi. Second, ports are named inconsistently. For example, the input port 'Midi Through 14:0' has a corresponding output named 'Midi Through:0'. Unless this was intended, it is a bug in RtMidi's ALSA implementation. PortMidi -------- Name: ``mido.backends.portmidi`` The PortMidi backend is written with ``ctypes`` and requires only the shared library file ``portmidi.so`` or ``portmidi.dll``. Can send but doesn't receive ``active_sensing`` messages. PortMidi has no callback mechanism, so callbacks are implemented in Python with threads. Each port with a callback has a dedicated thread doing blocking reads from the device. Due to limitations in PortMidi the port list will not be up-to-date if there are any ports open. (The refresh is implemented by re-initalizing PortMidi which would break any open ports.) Pygame ------ Name: ``mido.backends.pygame`` The Pygame backend uses ``pygame.midi`` for I/O. Can send but not receive ``sysex`` and ``active_sensing``. Callbacks are currently not implemented. Pygame.midi is implemented on top of PortMidi. mido-1.1.18/docs/conf.py0000664000175000017500000001730512775440355015223 0ustar olembolemb00000000000000# -*- coding: utf-8 -*- # # Mido documentation build configuration file, created by # sphinx-quickstart on Wed Jun 26 16:58:08 2013. # # This file is execfile()d with the current directory set to its containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('..')) import mido from mido import __version__ # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'Mido' copyright = u'Ole Martin Bjørndalen' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = __version__ # The full version, including alpha/beta/rc tags. release = __version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). #add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. #show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] # -- Options for HTML output --------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. #html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. #html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. #html_domain_indices = True # If false, no index is generated. #html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. #html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'Midodoc' # -- Options for LaTeX output -------------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). #'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'Mido.tex', u'Mido Documentation', u'Ole Martin Bjørndalen', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. #latex_use_parts = False # If true, show page references after internal links. #latex_show_pagerefs = False # If true, show URL addresses after external links. #latex_show_urls = False # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_domain_indices = True # -- Options for manual page output -------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'mido', u'Mido Documentation', [u'Ole Martin Bjørndalen'], 1) ] # If true, show URL addresses after external links. #man_show_urls = False # -- Options for Texinfo output ------------------------------------------------ # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ ('index', 'Mido', u'Mido Documentation', u'Ole Martin Bjørndalen', 'Mido', 'MIDI Objects for Python', 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. #texinfo_appendices = [] # If false, no module index is generated. #texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' mido-1.1.18/docs/acknowledgements.rst0000664000175000017500000000036112775440355020002 0ustar olembolemb00000000000000Acknowledgements ================ Thanks to /u/tialpoy/ on Reddit for extensive code review and helpful suggestions. Thanks to everyone who has sent bug reports and patches. The PortMidi wrapper is based on portmidizero by Grant Yoshida. mido-1.1.18/docs/messages.rst0000664000175000017500000000622513002711347016246 0ustar olembolemb00000000000000Messages ======== A Mido message is a Python object with methods and attributes. The attributes will vary depending on message type. To create a new message:: >>> mido.Message('note_on') You can pass attributes as keyword arguments:: >>> mido.Message('note_on', note=100, velocity=3, time=6.2) All attributes will default to 0. The exceptions are ``velocity``, which defaults to 64 (middle velocity) and ``data`` which defaults to ``()``. You can set and get attributes as you would expect:: >>> msg = mido.Message('note_on') >>> msg.note 0 The ``type`` attribute can be used to determine message type:: >>> msg.type 'note_on' Attributes are also settable but it's always better to use ``msg.copy()``:: >>> msg.copy(note=99, time=100.0) Mido supports all message types defined by the MIDI standard. For a full list of messages and their attributes, see :doc:`message_types`. Converting To Bytes ------------------- You can convert a message to MIDI bytes with one of these methods: >>> msg = mido.Message('note_on') >>> msg >>> msg.bytes() [144, 0, 64] >>> msg.bin() bytearray(b'\x90\x00@') >>> msg.hex() '90 00 40' You can turn bytes back into messages with the :doc:`parser `. The Time Attribute ------------------ Each message has a ``time`` attribute, which can be set to any value of type ``int`` or ``float`` (and in Python 2 also ``long``). What you do with this value is entirely up to you. Some parts of Mido use the attribute for special purposes. In MIDI file tracks, it is used as delta time (in ticks). .. note:: Before 1.1.18 the ``time`` attribute was not included in comparisons. If you want the old behavior the easies way is ``msg1.bytes()`` == ``msg2.bytes()``. To sort messages on time you can do:: messages.sort(key=lambda message: message.time) or:: import operator messages.sort(key=operator.attrgetter('time')) System Exclusive Messages ------------------------- System Exclusive (SysEx) messages are used to send device specific data. The ``data`` attribute is a tuple of data bytes which serves as the payload of the message:: >>> msg = Message('sysex', data=[1, 2, 3]) >>> msg >>> msg.hex() 'F0 01 02 03 F7' You can also extend the existing data:: >>> msg = Message('sysex', data=[1, 2, 3]) >>> msg.data += [4, 5] >>> msg.data += [6, 7, 8] >>> msg Any sequence of integers is allowed, and type and range checking is applied to each data byte. These are all valid:: (65, 66, 67) [65, 66, 67] (i + 65 for i in range(3)) (ord(c) for c in 'ABC') bytearray(b'ABC') b'ABC' # Python 3 only. For example:: >>> msg = Message('sysex', data=bytearray(b'ABC')) >>> msg.data += bytearray(b'DEF') >>> msg mido-1.1.18/docs/socket_ports.rst0000664000175000017500000000742112775440355017173 0ustar olembolemb00000000000000Socket Ports - MIDI over TCP/IP =============================== About Socket Ports ------------------ Socket ports allow you to send MIDI messages over a computer network. The protocol is standard MIDI bytes over a TCP stream. Caveats ------- The data is sent over an unencrypted channel. Also, the default server allows connections from any host and also accepts arbitrary sysex messages, which could allow anyone to for example overwrite patches on your synths (or worse). Use only on trusted networks. If you need more security, you can build a custom server with a white list of clients that are allowed to connect. If timing is critical, latency and jitter (especially on wireless networks) may make socket ports unusable. Sending Messages to a Server ---------------------------- First, let's import some things:: from mido.sockets import PortServer, connect After that, a simple server is only two lines:: for message in PortServer('localhost', 8080): print(message) You can then connect to the server and send it messages:: output = connect('localhost', 8080): output.send(message) Each end of the connection behaves like a normal Mido I/O port, with all the usual methods. The host may be a DNS host name or IP address (as a string). It may also be '', in which case connections are accepted on any ip address on the computer. Turning Things on their Head ---------------------------- If you want the server to send messages the client, you can instead do:: server = PortServer('localhost', 8080): while True: server.send(message) ... and then on the client side:: for message in connect('localhost', 8080): print(message) The client will now print any message that the server sends. Each message that the server sends will be received by all connected clients. Under the Hood -------------- The examples above use the server and client ports as normal I/O ports. This makes it easy to write simple servers, but you don't have any control connections and the way messages are sent and received. To get more control, you can ignore all the other methods of the ``PortServer`` object and use only ``accept()``. Here's a simple server implemented this way:: with PortServer('localhost', 8080) as server: while True: client = server.accept() for message in client: print(message) ``accept()`` waits for a client to connect, and returns a SocketPort object which is connected to the SocketPort object returned by ``connect()`` at the other end. The server above has one weakness: it allows only one connection at a time. You can get around this by using ``accept(block=False)``. This will return a SocketPort if there is a connection waiting and None if there is connection yet. Using this, you can write the server any way you like, for example:: with PortServer('localhost', 8080) as server: clients = [] while True: # Handle connections. client = server.accept(block=False) if client: print('Connection from {}'.format(client.name)) clients.append(client) for i, client in reversed(enumerate(clients)): if client.closed: print('{} disconnected'.format(client.name)) del clients[i] # Receive messages. for client in clients: for message in client.iter_pending() print('Received {} from {}'.format(message, client)) # Do other things ... Possible Future Additions ------------------------- Optional HTTP-style headers could be added. As long as these are 7-bit ASCII, they will be counted as data bytes and ignored by clients or servers who don't expect them. mido-1.1.18/docs/about_midi.rst0000664000175000017500000000544113002711347016552 0ustar olembolemb00000000000000About MIDI ========== A Short Introduction To MIDI ---------------------------- MIDI is a simple binary protocol for communicating with synthesizers and other electronic music equipment. It was developed in 1981 by Dave Smith and Chet Wood of Sequential Systems. MIDI was quickly embraced by all the major synth manufacturers and led to developments such as microcomputer sequencers, and with them the electronic home studio. Although many attempts have been made to replace it, it is still the industry standard. MIDI was designed for the 8-bit micro controllers found in synthesizers at the beginning of the 80's. As such, it is a very minimal byte-oriented protocol. The message for turning a note on is only three bytes long (here shown in hexadecimal):: 92 3C 64 This message consists of:: 92 -- 9 == message type note on 2 == channel 2 3C -- note 60 (middle C) 64 -- velocity (how hard the note is hit) The first byte is called a status byte. It has the upper bit set, which is how you can tell it apart from the following data bytes. Data bytes are thus only 7 bits (0..127). Each message type has a given number of data bytes, the exception being the System Exclusive message which has a start and a stop byte and any number of data bytes in-between these two:: F0 ... F7 Messages can be divided into four groups: * Channel messages. These are used to turn notes on and off, to change patches, and change controllers (pitch bend, modulation wheel, pedal and many others). There are 16 channels, and the channel number is encoded in the lower 4 bits of the status byte. Each synth can choose which channel (or channels) it responds to. This can typically be configured. * System common messages. * System real time messages, the include start, stop, continue, song position (for playback of songs) and reset. * System Exclusive messages (often called Sysex messages). These are used for sending and receiving device specific such as patch data. Some Examples of Messages ------------------------- :: # Turn on middle C on channel 2: 92 3C 64 # Turn it back off: 82 3C 64 # Change to program (sound) number 4 on channel 2: C2 04 # Continue (Starts a song that has been paused): FB # Sysex data request for the Roland SH-201 synthesizer: F0 41 10 00 00 16 11 20 00 00 00 00 00 00 21 3F F7 Further Reading --------------- * `An Introduction to MIDI `_ * `MIDI Basics `_ (by Yamaha) * `Wikipedia's page on MIDI `_ * `MIDI Manufacturers Association `_ * `A full table of MIDI messages `_ mido-1.1.18/docs/syx.rst0000664000175000017500000000153712775440355015301 0ustar olembolemb00000000000000SYX Files ========= SYX files are used to store SysEx messages, usually for patch data. Reading and Writing ------------------- To read a SYX file:: messages = mido.read_syx_file('patch.syx') To write a SYX file:: mido.write_syx_file('patch.syx', messages) Non-sysex messages will be ignored. Plain Text Format ----------------- Mido also supports plain text SYX files. These are read in exactly the same way:: messages = mido.read_syx_file('patch.txt') ``read_syx_file()`` determins which format the file is by looking at the first byte. It Raises ValueError if file is plain text and byte is not a 2-digit hex number. To write plain text:: mido.write_syx_file('patch.txt', messages, plaintext=True) This will write the messages as hex encoded bytes with one message per line:: F0 00 01 5D 02 00 F7 F0 00 01 5D 03 00 F7 mido-1.1.18/docs/changes.rst0000664000175000017500000003203113002711347016041 0ustar olembolemb00000000000000Changes ======= Release History --------------- 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: .. code-block:: python 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: .. code-block:: python 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. mido-1.1.18/docs/license.rst0000664000175000017500000000213312775440355016071 0ustar olembolemb00000000000000License ======= The MIT License (MIT) Copyright (c) 2013-infinity Ole Martin Bjørndalen 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. mido-1.1.18/docs/parsing.rst0000664000175000017500000000357513002711347016107 0ustar olembolemb00000000000000Parsing MIDI Bytes ================== MIDI is a binary protocol. Each each message is encoded as a status byte followed by up to three data bytes. (Sysex messages can have any number of data bytes and use a stop byte instead.) Mido comes with a parser that turns MIDI bytes into messages. You can create a parser object, or call one of the utility functions:: >>> mido.parse([0x92, 0x10, 0x20]) >>> mido.parse_all([0x92, 0x10, 0x20, 0x82, 0x10, 0x20]) [, ] These functions are just shortcuts for the full ``Parser`` class. This is the parser used inside input ports to parse incoming messages. Here are a few examples of how it can be used:: >>> p = mido.Parser() >>> p.feed([0x90, 0x10, 0x20]) >>> p.pending() 1 >>> p.get_message() >>> p.feed_byte(0x90) >>> p.feed_byte(0x10) >>> p.feed_byte(0x20) >>> p.feed([0x80, 0x10, 0x20]) ``feed()`` accepts any iterable that generates integers in 0..255. The parser will skip and stray status bytes or data bytes, so you can safely feed it random data and see what comes out the other end. ``get_message()`` will return ``None`` if there are no messages ready to be gotten. You can also fetch parsed messages out of the parser by iterating over it:: >>> p.feed([0x92, 0x10, 0x20, 0x82, 0x10, 0x20]) >>> for message in p: ... print(message) note_on channel=2 note=16 velocity=32 time=0 note_off channel=2 note=16 velocity=32 time=0 The messages are available in `p.messages` (a `collections.deque`). For the full table of MIDI binary encoding, see: ``_ mido-1.1.18/docs/message_types.rst0000664000175000017500000000471312775440355017325 0ustar olembolemb00000000000000Message Types ============= Supported Messages ------------------ ============== ============================== Name Keyword Arguments / Attributes ============== ============================== note_off channel note velocity note_on channel note velocity polytouch channel note value control_change channel control value program_change channel program aftertouch channel value pitchwheel channel pitch sysex data quarter_frame frame_type frame_value songpos pos song_select song tune_request clock start continue stop active_sensing reset ============== ============================== ``quarter_frame`` is used for SMPTE time codes. See: http://www.electronics.dit.ie/staff/tscarff/Music_technology/midi/MTC.htm Parameter Types --------------- =========== ====================== ================ Name Valid Range Default Value =========== ====================== ================ channel 0..15 0 frame_type 0..7 0 frame_value 0..15 0 control 0..127 0 note 0..127 0 program 0..127 0 song 0..127 0 value 0..127 0 velocity 0..127 64 data (0..127, 0..127, ...) () (empty tuple) pitch -8192..8191 0 pos 0..16383 0 time any integer or float 0 =========== ====================== ================ .. note:: Mido numbers channels 0 to 15 instead of 1 to 16. This makes them easier to work with in Python but you may want to add and subtract 1 when communicating with the user. ``velocity`` is how fast the note was struck or released. It defaults to 64 so that if you don't set it, you will still get a reasonable value. (64 is the recommended default for devices that don't support it attack or release velocity.) The ``time`` parameter is not included in the encoded message, and is (currently) not used by Mido in any way. You can use it for whatever purpose you wish. The ``data`` parameter accepts any iterable that generates numbers in 0..127. This includes:: mido.Message('sysex', data=[1, 2, 3]) mido.Message('sysex', data=range(10)) mido.Message('sysex', data=(i for i in range(10) if i % 2 == 0)) For details about the binary encoding of a MIDI message, see: http://www.midi.org/techspecs/midimessages.php mido-1.1.18/docs/images/0000775000175000017500000000000013002711364015144 5ustar olembolemb00000000000000mido-1.1.18/docs/images/midi_time.svg0000664000175000017500000004754713002711347017647 0ustar olembolemb00000000000000 image/svg+xml Minutes Beats Ticks 4 beats per minute (BPM) 3 ticks per beat mido-1.1.18/docs/string_encoding.rst0000664000175000017500000000563312775440355017633 0ustar olembolemb00000000000000String Encoding =============== Mido messages can be serialized to a text format, which can be used to safely store messages in text files, send them across sockets or embed them in JSON, among other things. To encode a message, simply call ``str()`` on it:: >>> cc = control_change(channel=9, control=1, value=122, time=60) >>> str(cc) 'control_change channel=9 control=1 value=122 time=60' Alternatively, you can the ``format_as_string`` function directly: >>> mido.format_as_string(cc) 'control_change channel=9 control=1 value=122 time=60' If you don't need the time attribute or you want to store it elsewhere, you can pass ``include_time=False``:: >>> mido.format_as_string(cc) 'control_change channel=9 control=1 value=122' Format ------ The format is simple:: MESSAGE_TYPE [PARAMETER=VALUE ...] These are the same as the arguments to ``mido.Message()``. The order of parameters doesn't matter, but each one can only appear once. Only these character will ever occur in a string encoded Mido message:: [a-z][0-9][ =_.+()] or written out:: 'abcdefghijklmnopqrstuvwxyz0123456789 =_.+()' This means the message can be embedded in most text formats without any form of escaping. Parsing ------- To parse a message, you can use ``mido.parse_string()``:: >>> parse_string('control_change control=1 value=122 time=0.5') Parameters that are left out are set to their default values. ``ValueError`` is raised if the message could not be parsed. Extra whitespace is ignored:: >>> parse_string(' control_change control=1 value=122') To parse messages from a stream, you can use ``mido.messages.parse_string_stream()``:: for (message, error) in parse_string_stream(open('some_music.text')): if error: print(error) else: do_something_with(message) This will return every valid message in the stream. If a message could not be parsed, ``message`` will be ``None`` and ``error`` will be an error message describing what went wrong, as well as the line number where the error occurred. The argument to ``parse_string_stream()`` can be any object that generates strings when iterated over, such as a file or a list. ``parse_string_stream()`` will ignore blank lines and comments (which start with a # and go to the end of the line). An example of valid input:: # A very short song with an embedded sysex message. note_on channel=9 note=60 velocity=120 time=0 # Send some data sysex data=(1,2,3) time=0.5 pitchwheel pitch=4000 # bend the not a little time=0.7 note_off channel=9 note=60 velocity=60 time=1.0 Examples -------- And example of messages embedded in JSON:: {'messages': [ '0.0 note_on channel=9 note=60 velocity=120', '0.5 sysex data=(1,2,3)', ... ]) mido-1.1.18/docs/contributing.rst0000664000175000017500000000437713002711347017154 0ustar olembolemb00000000000000Contributing ============ Branches and Pull Requests -------------------------- There master branch is for the latest stable relese. Please use the develop branch as a starting point and send your pull requests there: https://github.com/olemb/mido/tree/develop/ This will make it easier to merge your changes. Testing ------- `pytest `_ is used for unit testing. The tests are found in `mido/test_*.py`. If you can please run tests in both Python 2 and Python 3 before you commit code. I've renamed the executables so I can just run `pytest2 && pytest3` instead of remembering what the programs are called. (I think they were `py.test` and `py.test-3`.) You can also set up a commit hook:: echo "pytest2 && pytest3" >.git/hooks/pre-commit chmod +x .git/hooks/pre-commit This will run tests when you commit and cancel the commit if any tests fail. Testing MIDI file support ------------------------- Test Files ^^^^^^^^^^ The `Lakh MIDI Dataset `_ is a great resouce for testing the MIDI file parser. Publishing (Release Checklist) ------------------------------ I am currently the only one with access to publishing on PyPI and readthedocs. This will hopefully change in the future. First Time: Register With PyPI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: ./setup.py register Test ^^^^ :: rm -rf docs/_build && ./setup.py docs pytest2 && pytest3 check-manifest -v (`pip3 install check-manifest`) You can also test that the package installs by installing it in a virtualenv with `pip` and `easy_install` (Python 2 and 3) and importing it. This is a bit tedious. Perhaps there is a good way to automate it. Bump Version ^^^^^^^^^^^^ X.Y.Z is the version, for example 1.1.18 or 1.2.0. * update version and date in `docs/changes.rst` * update version in `mido/__init__.py` * `git commit -a -c "Bumped version to X.Y.Z."` Then: :: git tag X.Y.Z git push git push --tags Publish ^^^^^^^ Publish to GitHub master branch:: git checkout master git pull . develop git push Make sure we're back on `develop`:: git checkout develop Publish in PyPI:: python setup.py publish python setup.py bdist_wheel upload Last thing: * update readthedocs mido-1.1.18/docs/midi_files.rst0000664000175000017500000001604313002711347016542 0ustar olembolemb00000000000000MIDI Files ========== MidiFile objects can be used to read, write and play back MIDI files. Opening a File -------------- You can open a file with:: from mido import MidiFile mid = MidiFile('song.mid') .. note:: Sysex dumps such as patch data are often stored in SYX files rather than MIDI files. If you get "MThd not found. Probably not a MIDI file" try ``mido.read_syx_file()``. (See :doc:`syx` for more.) The ``tracks`` attribute is a list of tracks. Each track is a list of messages and meta messages, with the ``time`` attribute of each messages set to its delta time (in ticks). (See Tempo and Beat Resolution below for more on delta times.) To print out all messages in the file, you can do:: for i, track in enumerate(mid.tracks): print('Track {}: {}'.format(i, track.name)) for message in track: print(message) The entire file is read into memory. Thus you can freely modify tracks and messages, and save the file back by calling the ``save()`` method. (More on this below.) Iterating Over Messages ----------------------- Iterating over a ``MidiFile`` object will generate all MIDI messages in the file in playback order. The ``time`` attribute of each message is the number of seconds since the last message or the start of the file. Meta messages will also be included. If you want to filter them out, you can do:: if isinstance(message, MetaMessage): ... This makes it easy to play back a MIDI file on a port:: for message in MidiFile('song.mid'): time.sleep(message.time) if not isinstance(message, MetaMessage): port.send(message) This is so useful that there's a method for it:: for message in MidiFile('song.mid').play(): port.send(message) This does the sleeping and filtering for you. If you pass ``meta_messages=True`` you will also get meta messages. These can not be sent on ports, which is why they are off by default. Creating a New File ------------------- You can create a new file by calling MidiFile without the ``filename`` argument. The file can then be saved by calling the ``save()`` method:: from mido import Message, MidiFile, MidiTrack mid = MidiFile() track = MidiTrack() mid.tracks.append(track) track.append(Message('program_change', program=12, time=0)) track.append(Message('note_on', note=64, velocity=64, time=32)) track.append(Message('note_off', note=64, velocity=127, time=32)) mid.save('new_song.mid') The ``MidiTrack`` class is a subclass of list, so you can use all the usual methods. All messages must be tagged with delta time (in ticks). (A delta time is how long to wait before the next message.) If there is no 'end_of_track' message at the end of a track, one will be written anyway. A complete example can be found in ``examples/midifiles/``. The ``save`` method takes either a filename (``str``) or, using the ``file`` keyword parameter, a file object such as an in-memory binary file (an ``io.BytesIO``). If you pass a file object, ``save`` does not close it. Similarly, the ``MidiFile`` constructor can take either a filename, or a file object by using the ``file`` keyword parameter. if you pass a file object to ``MidiFile`` as a context manager, the file is not closed when the context manager exits. Examples can be found in ``test_midifiles2.py``. File Types ---------- There are three types of MIDI files: * type 0 (single track): all messages are saved in one track * type 1 (synchronous): all tracks start at the same time * type 2 (asynchronous): each track is independent of the others When creating a new file, you can select type by passing the ``type`` keyword argument, or by setting the ``type`` attribute:: mid = MidiFile(type=2) mid.type = 1 Type 0 files must have exactly one track. A ``ValueError`` is raised if you attempt to save a file with no tracks or with more than one track. Playback Length --------------- You can get the total playback time in seconds by accessing the ``length`` property:: mid.length This is only supported for type 0 and 1 files. Accessing ``length`` on a type 2 file will raise ``ValueError``, since it is impossible to compute the playback time of an asynchronous file. Meta Messages ------------- Meta messages behave like normal messages and can be created in the usual way, for example:: >>> from mido import MetaMessage >>> MetaMessage('key_signature', key='C#', mode='major') You can tell meta messages apart from normal messages with:: if isinstance(message, MetaMessage): ... or if you know the message type you can use the ``type`` attribute:: if message.type == 'key_signature': ... elif message.type == 'note_on': ... Meta messages can not be sent on ports. For a list of supported meta messages and their attributes, and also how to implement new meta messages, see :doc:`meta_message_types`. About the Time Attribute ------------------------ The ``time`` attribute is used in several different ways: * inside a track, it is delta time in ticks. This must be an integer. * in messages yielded from ``play()``, it is delta time in seconds (time elapsed since the last yielded message) * (only important to implementers) inside certain methods it is used for absolute time in ticks or seconds Tempo and Beat Resolution ------------------------- .. image:: images/midi_time.svg Timing in MIDI files is all centered around beats. A beat is the same as a quarter note. Tempo is given in microseconds per beat, and beats are divided into ticks. The default tempo is 500000 microseconds per beat (quarter note), which is half a second per beat or 120 beats per minute. The meta message 'set_tempo' can be used to change tempo during a song. You can use :py:func:`bpm2tempo` and :py:func:`tempo2bpm` to convert to and from beats per minute. Note that :py:func:`tempo2bpm` may return a floating point number. Computations:: beats_per_seconds = 1000000 / tempo beats_per_minute = (1000000 / tempo) * 60 tempo = (60 / beats_per_minute) * 1000000 Examples:: 2 == 1000000 / 500000 120 == (1000000 / 500000) * 60 500000 == (60 / 120.0) * 1000000 Each message in a MIDI file has a delta time, which tells how many ticks has passed since the last message. The length of a tick is defined in ticks per beat. This value is stored as ``ticks_per_beat`` in the file header and remains fixed throughout the song. It is used when converting delta times to and from real time. (Todo: what's the default value?) Computations:: seconds_per_beat = tempo / 1000000.0 seconds_per_tick = seconds_per_beat / float(ticks_per_beat) time_in_seconds = time_in_ticks * seconds_per_tick time_in_ticks = time_in_seconds / seconds_per_tick Examples:: 0.5 == 500000 / 1000000.0 0.005 == 0.5 / 100 1.0 == 200 * 0.005 200 == 1.0 / 0.005 (Todo: update with default value.) MidiFile objects have a ``ticks_per_beat`` attribute, while ``message.time`` is used for delta time. Tempo is updated by ``set_tempo`` meta messages. mido-1.1.18/docs/authors.rst0000664000175000017500000000011212775440355016127 0ustar olembolemb00000000000000Authors ======= Ole Martin Bjørndalen (lead programmer) Rapolas Binkys mido-1.1.18/docs/meta_message_types.rst0000664000175000017500000002130512775440355020327 0ustar olembolemb00000000000000Meta Message Types ================== Supported Messages ------------------ sequence_number (0x00) ^^^^^^^^^^^^^^^^^^^^^^ =============== ============ ======== Attribute Values Default =============== ============ ======== number 0..65535 0 =============== ============ ======== Sequence number in type 0 and 1 MIDI files; pattern number in type 2 MIDI files. text (0x01) ^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== text string '' ============== ============== ======== General "Text" Meta Message. Can be used for any text based data. copyright (0x02) ^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== text string '' ============== ============== ======== Provides information about a MIDI file's copyright. track_name (0x03) ^^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== name string '' ============== ============== ======== Stores a MIDI track's name. instrument_name (0x04) ^^^^^^^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== name string '' ============== ============== ======== Stores an instrument's name. lyrics (0x05) ^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== text string '' ============== ============== ======== Stores the lyrics of a song. Typically one syllable per Meta Message. marker (0x06) ^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== text string '' ============== ============== ======== Marks a point of interest in a MIDI file. Can be used as the marker for the beginning of a verse, solo, etc. cue_marker (0x07) ^^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== text string '' ============== ============== ======== Marks a cue. IE: 'Cue performer 1', etc device_name (0x09) ^^^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== name string '' ============== ============== ======== Gives the name of the device. channel_prefix (0x20) ^^^^^^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== channel 0..255 0 ============== ============== ======== Gives the prefix for the channel on which events are played. midi_port (0x21) ^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== port 0..255 0 ============== ============== ======== Gives the MIDI Port on which events are played. end_of_track (0x2f) ^^^^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== n/a n/a n/a ============== ============== ======== An empty Meta Message that marks the end of a track. set_tempo (0x51) ^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== tempo 0..16777215 500000 ============== ============== ======== Tempo is in microseconds per beat (quarter note). You can use :py:func:`bpm2tempo` and :py:func:`tempo2bpm` to convert to and from beats per minute. Note that :py:func:`tempo2bpm` may return a floating point number. smpte_offset (0x54) ^^^^^^^^^^^^^^^^^^^ ============== ================= ======== Attribute Values Default ============== ================= ======== frame_rate 24, 25, 29.97, 30 24 hours 0..255 0 minutes 0..59 0 seconds 0..59 0 frames 0..255 0 sub_frames 0..99 0 ============== ================= ======== time_signature (0x58) ^^^^^^^^^^^^^^^^^^^^^ ============================ =============== ======== Attribute Values Default ============================ =============== ======== numerator 0..255 4 denominator 1..2**255 4 clocks_per_click 0..255 24 notated_32nd_notes_per_beat 0..255 8 ============================ =============== ======== Time signature of: 4/4 : MetaMessage('time_signature', numerator=4, denominator=4) 3/8 : MetaMessage('time_signature', numerator=3, denominator=8) key_signature (0x59) ^^^^^^^^^^^^^^^^^^^^ ========= ================== ======== Attribute Values Default ========= ================== ======== key 'C', 'F#m', ... 'C' ========= ================== ======== Valid values: A A#m Ab Abm Am B Bb Bbm Bm C C# C#m Cb Cm D D#m Db Dm E Eb Ebm Em F F# F#m Fm G G#m Gb Gm Note: the mode attribute was removed in 1.1.5. Instead, an 'm' is appended to minor keys. sequencer_specific (0x7f) ^^^^^^^^^^^^^^^^^^^^^^^^^ ============== ============== ======== Attribute Values Default ============== ============== ======== data [..] [] ============== ============== ======== An unprocessed sequencer specific message containing raw data. Unknown Meta Messages --------------------- Unknown meta messages will be returned as ``UnknownMetaMessage`` objects, with ``type`` set to ``unknown_meta``. The messages are saved back to the file exactly as they came out. Code that depends on ``UnknownMetaMessage`` may break if the message in question is ever implemented, so it's best to only use these to learn about the format of the new message and then implement it as described below. ``UnknownMetaMessage`` have two attributes:: ``type_byte`` - a byte which uniquely identifies this message type ``_data`` - the message data as a list of bytes These are also visible in the ``repr()`` string:: Implementing New Meta Messages ------------------------------ If you come across a meta message which is not implemented, or you want to use a custom meta message, you can add it by writing a new meta message spec:: from mido.midifiles import MetaSpec, add_meta_spec class MetaSpec_light_color(MetaSpec): type_byte = 0xf0 attributes = ['r', 'g', 'b'] defaults = [0, 0, 0] def decode(self, message, data): # Interpret the data bytes and assign them to attributes. (message.r, message.g, message.b) = data def encode(self, message): # Encode attributes to data bytes and # return them as a list of ints. return [message.r, message.g, message.b] def check(self, name, value): # (Optional) # This is called when the user assigns # to an attribute. You can use this for # type and value checking. (Name checking # is already done. # # If this method is left out, no type and # value checking will be done. if not isinstance(value, int): raise TypeError('{} must be an integer'.format(name)) if not 0 <= value <= 255: raise TypeError('{} must be in range 0..255'.format(name)) Then you can add your new message type with:: add_meta_spec(MetaSpec_light_color) and create messages in the usual way:: >>> from mido import MetaMessage >>> MetaMessage('light_color', r=120, g=60, b=10) and the new message type will now work when reading and writing MIDI files. Some additional functions are available:: encode_string(unicode_string) decode_string(byte_list) These convert between a Unicode string and a list of bytes using the current character set in the file. If your message contains only one string with the attribute name ``text`` or ``name``, you can subclass from one of the existing messages with these attributes, for example:: class MetaSpec_copyright(MetaSpec_text): type_byte = 0x02 class MetaSpec_instrument_name(MetaSpec_track_name): type_byte = 0x04 This allows you to skip everything but ``type_byte``, since the rest is inherited. See the existing MetaSpec classes for further examples. mido-1.1.18/docs/intro.rst0000664000175000017500000001221713002711347015570 0ustar olembolemb00000000000000Introduction (Basic Concepts) ============================= Mido is all about messages and ports. Messages -------- Mido allows you to work with MIDI messages as Python objects. To create a new message:: >>> from mido import Message >>> msg = Message('note_on', note=60) >>> msg .. note:: Mido numbers channels 0 to 15 instead of 1 to 16. This makes them easier to work with in Python but you may want to add and subtract 1 when communicating with the user. A list of all supported message types and their parameters can be found in :doc:`message_types`. The values can now be accessed as attributes:: >>> msg.type 'note_on' >>> msg.note 60 >>> msg.velocity 64 Attributes are also settable but this should be avoided. It's better to use ``msg.copy()``:: >>> msg.copy(note=100, velocity=127) >> n = mido.Message('note_on') >>> n.channel = 2092389483249829834 Traceback (most recent call last): File "", line 1, in File "./mido/messages.py", line 327, in __setattr__ ret = check(value) File "./mido/messages.py", line 128, in check_channel raise ValueError('channel must be in range 0..15') ValueError: channel must be in range 0..15 and when you pass some nonsense as a keyword argument to the constructor or the copy() method:: >>> n.copy(note=['This', 'is', 'wrong']) Traceback (most recent call last): File "", line 1, in File "./mido/messages.py", line 316, in copy return Message(self.type, **args) File "./mido/messages.py", line 290, in __init__ setattr(self, name, value) File "./mido/messages.py", line 327, in __setattr__ ret = check(value) File "./mido/messages.py", line 181, in check_databyte raise TypeError('data byte must be an integer') TypeError: data byte must be an integer This means that the message object is always a valid MIDI message. Ports ----- To create an output port and send a message:: >>> outport = mido.open_output() >>> outport.send(msg) To create an input port and receive a message:: >>> inport = mido.open_input() >>> msg = inport.receive() .. note:: Multiple threads can safely send and receive notes on the same port. This will give you the default output and input ports. If you want to open a specific port, you will need its name. To get a list of all available input ports:: >>> mido.get_input_names() ['Midi Through Port-0', 'SH-201', 'Integra-7'] >>> inport = mido.open_input('SH-201') All Mido ports can be used with the ``with`` statement, which will close the port for you:: with mido.open_input('SH-201') as inport: ... To iterate through all incoming messages:: for msg in inport: ... You can also receive and iterate over messages in a non-blocking way. For more about ports, see :doc:`ports`. All Ports are Ports ------------------- The input and output ports used above are device ports, which communicate with a (physical or virtual) MIDI device. Other port types include: * ``MultiPort``, which wraps around a set of ports and allow you to send to all of them or receive from all of them as if they were one. * ``SocketPort``, which communicates with another port over a TCP/IP (network) connection. * ``IOPort``, which wraps around an input and an output port and allows you to send and receive messages as if the two were the same port. Ports of all types look and behave the same way, so they can be used interchangeably. It's easy to write new port types. See :doc:`implementing_ports`. Virtual Ports ------------- Virtual ports allow you to create new ports that other applications can connect to:: with mido.open_input('New Port', virtual=True) as inport: for message in port: print(message) The port should now appear to other applications as "New Port". Unfortunately virtual ports are not supported by PortMidi and Pygame so this only works with RtMidi. Parsing MIDI Bytes ------------------ Mido comes with a parser that allows you to turn bytes into messages. You can create a new parser:: >>> p = mido.Parser() >>> p.feed([0x90, 0x40]) >>> p.feed_byte(0x60) You can then fetch messages out of the parser:: >>> p.pending() 1 >>> for message in p: ... print(message) ... note_on channel=0 note=64 velocity=96 time=0 For more on parsers and parsing see :doc:`parsing`. Backends -------- Mido comes with backends for PortMidi and RtMidi and pygame. The default is PortMidi. You can select another backend or even use multiple backends at the same time. For more on this, see :doc:`backends`. mido-1.1.18/docs/freezing.rst0000664000175000017500000000217212775440355016263 0ustar olembolemb00000000000000Freezing Mido Programs ====================== PyInstaller ----------- When you build an executable with PyInstaller and run it you may get import errors like this one:: ImportError: No module named mido.backends.portmidi The reason is that Mido uses ``import_module()`` to import the backend modules, while PyInstaller looks for ``import`` statements. The easiest fix is to import the module at the top of the program:: import mido import mido.backends.portmidi # The backend you want to use. print(mido.get_input_names()) and then run ``pyinstaller`` like usual:: $ pyinstaller --onefile midotest.py $ ./dist/midotest [u'Midi Through Port-0'] If you don't want to change the program, you can instead declare the backend module as a `hidden import `_. bbFreeze, py2exe, cx_Freeze, py2app, etc. ----------------------------------------- I suspect the same is true for these, but I have not had a chance to try it out yet. Adding the explicit ``import`` statement should always work, though, since Mido backends are just normal Python modules. mido-1.1.18/docs/bin.rst0000664000175000017500000000252512775440355015224 0ustar olembolemb00000000000000Included Programs ================= These are installed with Mido. mido-play --------- Plays back one or more MIDI files:: $ mido-play song1.mid song2.mid mido-ports ---------- Lists available input and output ports and shows environment variables and the current backend module. mido-serve ---------- Serves one or more ports over the network, for example:: $ mido-serve :9080 'Integra-7' You can now connect to this port with ``mido-forward`` (or use ``mido.sockets.connect()`` and send messages to it. The messages will be forwarded to every port you listed (in this case 'Integra-7'). mido-connect ------------ Forwards all messages that arrive on one or more ports to a server. For example, to use the SH-201 keyboard connected to this computer to play sounds on the Integra-7 on a computer named ``mac.local`` (which runs the server as above), you can do:: $ mido-connect mac.local:9080 'SH-201' Note that you may experience latency and jitter, so this may not be very useful for live playing or for playing back songs. There is also no security built in, so you should only use this on a trusted network. (Anyone can connect and send anything, including harmful sysex messages.) ``mido-serve`` and ``mido-connect`` are only included as fun programs to play with, but may in the future be expanded into something more usable. mido-1.1.18/docs/index.rst0000664000175000017500000000401313002711347015537 0ustar olembolemb00000000000000.. Mido documentation master file, created by sphinx-quickstart on Wed Jun 26 16:58:08 2013. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Mido - MIDI Objects for Python ============================== Version |version| Mido is a library for working with MIDI messages and ports. It's designed to be as straight forward and Pythonic as possible. .. code-block:: python >>> import mido >>> output = mido.open_output() >>> output.send(mido.Message('note_on', note=60, velocity=64)) .. code-block:: python >>> with input as mido.open_input('SH-201'): ... for msg in input: ... print(msg) .. code-block:: python >>> from mido import Message >>> msg = Message('program_change', program=1) >>> msg >>> msg.copy(program=2, time=100) >>> msg.time 100 >>> msg.bytes() [192, 1] .. code-block:: python >>> from mido import MidiFile >>> for msg in MidiFile('song.mid').play(): ... output.send(msg) Mido is short for MIDi Objects. Source code ----------- Latest stable release: https://github.com/olemb/mido/ Latest development version: https://github.com/olemb/mido/tree/develop/ About This Document ------------------- This document is available at https://mido.readthedocs.io/ To build locally:: python setup.py docs This requires Sphinx. The resulting files can be found in ``docs/_build/``. Contents -------- .. toctree:: :maxdepth: 2 changes installing contributing intro messages ports midi_files syx backends parsing string_encoding socket_ports bin implementing_ports implementing_backends freezing about_midi message_types meta_message_types lib resources license authors acknowledgements Indices and tables ------------------ * :ref:`genindex` * :ref:`modindex` * :ref:`search` mido-1.1.18/docs/implementing_backends.rst0000664000175000017500000000230412775440355020771 0ustar olembolemb00000000000000Writing a New Backend ===================== A backend is a Python module with one or more of these:: Input -- an input port class Output -- an output port class IOPort -- an I/O port class get_devices() -- returns a list of devices Once written, the backend can be used by setting the environment variable ``MIDO_BACKEND`` or by calling ``mido.set_backend()``. In both cases, the path of the module is used. ``Input`` And input class for ``open_input()``. This is only required if the backend supports input. ``Output`` And output class for ``open_output()``. This is only required if the backend supports output. ``IOPort`` An I/O port class for ``open_ioport()``. If this is not found, ``open_ioport()`` will return ``mido.ports.IOPort(Input(), Output())``. ``get_devices(**kwargs)`` Returns a list of devices, where each device is dictionary with at least these three values:: { 'name': 'Some MIDI Input Port', 'is_input': True, 'is_output': False, } These are used to build return values for ``get_input_names()`` etc.. This function will also be available to the user directly. For examples, see ``mido/backends/``. mido-1.1.18/docs/resources.rst0000664000175000017500000000317412775440355016467 0ustar olembolemb00000000000000Resources ========= * `MIDI Manufacturers Association `_ (midi.org) * `Table of MIDI Messages `_ (midi.org) * `Tech Specs & Info `_ (midi.org) * `MIDI `_ (Wikipedia) * `Essentials of the MIDI Protocol `_ (Craig Stuart Sapp, CCRMA) * `Outline of the Standard MIDI File Structure `_ (Craig Stuart Sapp, CCRMA) * `Active Sense `_ (About the active sensing message.) * `Active Sensing `_ (Sweetwater) * `MIDI Technical/Programming Docs `_ (Jeff Glatt) * `Standard MIDI Files `_ (cnx.org) * `MIDI File Parsing `_ (Course assignment in `Music 253 `_ at Stanford University) * `MIDI File Format `_ (The Sonic Spot) * `Delta time and running status `_ (mic at recordingblogs.com) * `MIDI meta messages `_ (recordingblog.com) * `Meta Message `_ (Sound On Sound) mido-1.1.18/docs/lib.rst0000664000175000017500000000356712775440355015231 0ustar olembolemb00000000000000.. _api: Library Reference ================= Messages -------- .. module:: mido .. autoclass:: Message :members: :inherited-members: :undoc-members: Ports ----- .. autofunction:: open_input .. autofunction:: open_output .. autofunction:: open_ioport .. autofunction:: get_input_names .. autofunction:: get_output_names .. autofunction:: get_ioport_names Backends -------- .. autofunction:: set_backend .. autoclass:: Backend :members: :inherited-members: :undoc-members: Parsing ------- .. autofunction:: parse .. autofunction:: parse_all .. autoclass:: Parser :members: :inherited-members: :undoc-members: MIDI Files ----------- .. autoclass:: MidiFile :members: :inherited-members: :undoc-members: .. autoclass:: MidiTrack :members: :inherited-members: :undoc-members: .. autoclass:: MetaMessage :members: :inherited-members: :undoc-members: .. autofunction:: bpm2tempo .. autofunction:: tempo2bpm .. autofunction:: merge_tracks SYX Files --------- .. autofunction:: read_syx_file .. autofunction:: write_syx_file Port Classes and Functions -------------------------- .. module:: mido.ports .. autoclass:: BaseInput :members: :inherited-members: :undoc-members: .. autoclass:: BaseOutput :members: :inherited-members: :undoc-members: .. autoclass:: IOPort :members: :inherited-members: :undoc-members: .. autoclass:: MultiPort :members: :inherited-members: :undoc-members: .. autofunction:: multi_receive .. autofunction:: multi_iter_pending .. autofunction:: sleep .. autofunction:: set_sleep_time .. autofunction:: get_sleep_time Socket Ports ------------ .. module:: mido.sockets .. autoclass:: PortServer :members: :inherited-members: :undoc-members: .. autoclass:: SocketPort :members: :inherited-members: :undoc-members: .. autofunction:: parse_address mido-1.1.18/docs/make.bat0000664000175000017500000001174412775440355015332 0ustar olembolemb00000000000000@ECHO OFF REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) set BUILDDIR=_build set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . set I18NSPHINXOPTS=%SPHINXOPTS% . if NOT "%PAPER%" == "" ( set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% ) if "%1" == "" goto help if "%1" == "help" ( :help echo.Please use `make ^` where ^ is one of echo. html to make standalone HTML files echo. dirhtml to make HTML files named index.html in directories echo. singlehtml to make a single large HTML file echo. pickle to make pickle files echo. json to make JSON files echo. htmlhelp to make HTML files and a HTML help project echo. qthelp to make HTML files and a qthelp project echo. devhelp to make HTML files and a Devhelp project echo. epub to make an epub echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter echo. text to make text files echo. man to make manual pages echo. texinfo to make Texinfo files echo. gettext to make PO message catalogs echo. changes to make an overview over all changed/added/deprecated items echo. linkcheck to check all external links for integrity echo. doctest to run all doctests embedded in the documentation if enabled goto end ) if "%1" == "clean" ( for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i del /q /s %BUILDDIR%\* goto end ) if "%1" == "html" ( %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end ) if "%1" == "dirhtml" ( %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. goto end ) if "%1" == "singlehtml" ( %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. goto end ) if "%1" == "pickle" ( %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the pickle files. goto end ) if "%1" == "json" ( %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the JSON files. goto end ) if "%1" == "htmlhelp" ( %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run HTML Help Workshop with the ^ .hhp project file in %BUILDDIR%/htmlhelp. goto end ) if "%1" == "qthelp" ( %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Mido.qhcp echo.To view the help file: echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Mido.ghc goto end ) if "%1" == "devhelp" ( %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp if errorlevel 1 exit /b 1 echo. echo.Build finished. goto end ) if "%1" == "epub" ( %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub if errorlevel 1 exit /b 1 echo. echo.Build finished. The epub file is in %BUILDDIR%/epub. goto end ) if "%1" == "latex" ( %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex if errorlevel 1 exit /b 1 echo. echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. goto end ) if "%1" == "text" ( %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text if errorlevel 1 exit /b 1 echo. echo.Build finished. The text files are in %BUILDDIR%/text. goto end ) if "%1" == "man" ( %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man if errorlevel 1 exit /b 1 echo. echo.Build finished. The manual pages are in %BUILDDIR%/man. goto end ) if "%1" == "texinfo" ( %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo if errorlevel 1 exit /b 1 echo. echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. goto end ) if "%1" == "gettext" ( %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale if errorlevel 1 exit /b 1 echo. echo.Build finished. The message catalogs are in %BUILDDIR%/locale. goto end ) if "%1" == "changes" ( %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes if errorlevel 1 exit /b 1 echo. echo.The overview file is in %BUILDDIR%/changes. goto end ) if "%1" == "linkcheck" ( %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck if errorlevel 1 exit /b 1 echo. echo.Link check complete; look for any errors in the above output ^ or in %BUILDDIR%/linkcheck/output.txt. goto end ) if "%1" == "doctest" ( %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest if errorlevel 1 exit /b 1 echo. echo.Testing of doctests in the sources finished, look at the ^ results in %BUILDDIR%/doctest/output.txt. goto end ) :end mido-1.1.18/docs/installing.rst0000664000175000017500000000264212775451011016607 0ustar olembolemb00000000000000Installing Mido =============== Requirements ------------ Mido targets Python 2.7 and 3.2. It is developed and tested in Ubuntu and Mac OS X, but should also work in Windows. Everything is implemented in pure Python, so no compilation is required. There are no external dependencies unless you want to use the port backends, which are loaded on demand. Mido comes with backends for `PortMidi `_, `python-rtmidi `_ and `Pygame `_. Installing ---------- To install:: $ pip install mido Installing PortMidi (Optional) ------------------------------ PortMidi is available in Ubuntu as ``libportmidi-dev`` and in `MacPorts `_ and `Homebrew `_ as ``portmidi``. Installing python-rtmidi (Optional) ----------------------------------- python-rtmidi requires ``librtmidi.so``, which is available in Ubuntu as ``librtmidi-dev`` (and possible also available as a package in MacPorts and Homebrew. Ideally this should work:: $ pip install python-rtmidi but the package appears to be broken in PyPI. To get around this you can do:: $ pip install --pre python-rtmidi The ``--pre`` is because pip refuses to install when the library looks like a pre-release, and says: "Could not find a version that satisfies the requirement XYZ.") mido-1.1.18/docs/Makefile0000664000175000017500000001266412775440354015366 0ustar olembolemb00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" @echo " text to make text files" @echo " man to make manual pages" @echo " texinfo to make Texinfo files" @echo " info to make Texinfo files and run them through makeinfo" @echo " gettext to make PO message catalogs" @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: -rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Mido.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Mido.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" @echo "# mkdir -p $$HOME/.local/share/devhelp/Mido" @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Mido" @echo "# devhelp" epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." texinfo: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." info: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." gettext: $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." mido-1.1.18/MANIFEST.in0000664000175000017500000000065613002711347014515 0ustar olembolemb00000000000000include README.rst LICENSE run_tests.py recursive-include examples *.py recursive-include extras *.py include docs/_static/PLACEHOLDER recursive-include docs *.bat recursive-include docs *.py recursive-include docs *.rst recursive-include docs Makefile recursive-include examples *.py recursive-include examples *.sh recursive-include extras *.rst recursive-include mido *.py recursive-include docs/images *.svg prune docs/_build mido-1.1.18/run_tests.py0000775000175000017500000000077312775440355015400 0ustar olembolemb00000000000000#!/usr/bin/env python """ Runs tests in Python 2 and 3. If you want tests to run before each commit you can install this as a pre-commit hook: ln -sf ../../run_tests.py .git/hooks/pre-commit The commit will now be canceled if tests fail. """ import os import sys sys.path.insert(0, '.') def print_yellow(message): print('\033[0;33m{}\033[0m'.format(message)) print_yellow('Python 2') if os.system('py.test'): sys.exit(1) print_yellow('Python 3') if os.system('py.test-3'): sys.exit(1) mido-1.1.18/LICENSE0000664000175000017500000000210412775440354013767 0ustar olembolemb00000000000000The MIT License Copyright (c) 2013-infinity Ole Martin Bjørndalen 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. mido-1.1.18/PKG-INFO0000664000175000017500000001405013002711364014044 0ustar olembolemb00000000000000Metadata-Version: 1.1 Name: mido Version: 1.1.18 Summary: MIDI Objects for Python Home-page: https://mido.readthedocs.io/ Author: Ole Martin Bjorndalen Author-email: ombdalen@gmail.com License: MIT Description: Mido - MIDI Objects for Python ============================== Mido is a library for working with MIDI messages and ports. It's designed to be as straight forward and Pythonic as possible: .. code-block:: python >>> import mido >>> output = mido.open_output() >>> output.send(mido.Message('note_on', note=60, velocity=64)) .. code-block:: python >>> with input as mido.open_input('SH-201'): ... for msg in input: ... print(msg) .. code-block:: python >>> from mido import Message >>> msg = Message('program_change', program=1) >>> msg >>> msg.copy(program=2, time=100) >>> msg.time 100 >>> msg.bytes() [192, 1] .. code-block:: python >>> from mido import MidiFile >>> for msg in MidiFile('song.mid').play(): ... output.send(msg) Full documentation at https://mido.readthedocs.io/ Main Features ------------- * works in Python 2 and 3. * convenient message objects. * supports PortMidi, RtMidi and Pygame. New backends are easy to write. * full support for all 18 messages defined by the MIDI standard. * standard port API allows all kinds of input and output ports to be used interchangeably. New port types can be written by subclassing and overriding a few methods.s * includes a reusable MIDI parser. * full support for MIDI files (read, write, create and play) with complete access to every message in the file, including all common meta messages. * can read and write SYX files (binary and plain text). * implements (somewhat experimental) MIDI over TCP/IP with socket ports. This allows for example wireless MIDI between two computers. * includes programs for playing MIDI files, listing ports and serving and forwarding ports over a network. Status ------ 1.1 is the second stable release. See docs/changes.rst for a full list of changes. Requirements ------------ Mido targets Python 2.7 and 3.2. If you want to use message ports, you will need `PortMidi `_ installed on your system. The PortMidi library is loaded on demand, so you can use the parser and messages without it. The PortMidi wrapper is tested on on Ubuntu and Mac OS X, but may also run on other systems where the ``portmidi.so/dll`` file is available. Alternative backends are included for `python-rtmidi `_ and `Pygame `_. These can be selected with the environment variable ``MIDO_BACKEND`` or by calling ``mido.set_backend()``. Like PortMidi, these are loaded on demand. Installing ---------- To install:: $ pip install mido The PortMidi wrapper is written with `ctypes`, so no compilation is required. If you want to use ports, you need the PortMidi shared library. The Ubuntu package is called ``libportmidi-dev``, while the `MacPorts `_ and `Homebrew `_ packages are called ``portmidi``. To build documentation locally:: python setup.py docs This requires Sphinx. The resulting files can be found in ``docs/_build/``. Known Bugs ---------- * in OS X, PortMidi and RtMidi usually hang for a second or two seconds while initializing. This is actually not a Mido bug, but something that happens at a lower level. * PortMidi in Ubuntu is mistakenly compiled in debug mode, which causes it to print out error message instead of returning an error code:: PortMidi: `Bad pointer' type ENTER...PortMidi call failed... See https://bugs.launchpad.net/ubuntu/+source/portmidi/+bug/890600 This means here is no way for Mido to catch the error and raise an exception. This regularity occurs in two places: in PortMidi when you close a port that has a callback, and in Pygame when you close any port. Source Code ----------- Latest version of the code: https://github.com/olemb/mido/ . Latest development version: https://github.com/olemb/mido/tree/develop/ License ------- Mido is released under the terms of the `MIT license `_. Contact ------- Ole Martin Bjorndalen - ombdalen@gmail.com Platform: UNKNOWN Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Developers Classifier: Natural Language :: English Classifier: License :: OSI Approved :: MIT License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3.2 mido-1.1.18/README.rst0000664000175000017500000001030413002711347014435 0ustar olembolemb00000000000000Mido - MIDI Objects for Python ============================== Mido is a library for working with MIDI messages and ports. It's designed to be as straight forward and Pythonic as possible: .. code-block:: python >>> import mido >>> output = mido.open_output() >>> output.send(mido.Message('note_on', note=60, velocity=64)) .. code-block:: python >>> with input as mido.open_input('SH-201'): ... for msg in input: ... print(msg) .. code-block:: python >>> from mido import Message >>> msg = Message('program_change', program=1) >>> msg >>> msg.copy(program=2, time=100) >>> msg.time 100 >>> msg.bytes() [192, 1] .. code-block:: python >>> from mido import MidiFile >>> for msg in MidiFile('song.mid').play(): ... output.send(msg) Full documentation at https://mido.readthedocs.io/ Main Features ------------- * works in Python 2 and 3. * convenient message objects. * supports PortMidi, RtMidi and Pygame. New backends are easy to write. * full support for all 18 messages defined by the MIDI standard. * standard port API allows all kinds of input and output ports to be used interchangeably. New port types can be written by subclassing and overriding a few methods.s * includes a reusable MIDI parser. * full support for MIDI files (read, write, create and play) with complete access to every message in the file, including all common meta messages. * can read and write SYX files (binary and plain text). * implements (somewhat experimental) MIDI over TCP/IP with socket ports. This allows for example wireless MIDI between two computers. * includes programs for playing MIDI files, listing ports and serving and forwarding ports over a network. Status ------ 1.1 is the second stable release. See docs/changes.rst for a full list of changes. Requirements ------------ Mido targets Python 2.7 and 3.2. If you want to use message ports, you will need `PortMidi `_ installed on your system. The PortMidi library is loaded on demand, so you can use the parser and messages without it. The PortMidi wrapper is tested on on Ubuntu and Mac OS X, but may also run on other systems where the ``portmidi.so/dll`` file is available. Alternative backends are included for `python-rtmidi `_ and `Pygame `_. These can be selected with the environment variable ``MIDO_BACKEND`` or by calling ``mido.set_backend()``. Like PortMidi, these are loaded on demand. Installing ---------- To install:: $ pip install mido The PortMidi wrapper is written with `ctypes`, so no compilation is required. If you want to use ports, you need the PortMidi shared library. The Ubuntu package is called ``libportmidi-dev``, while the `MacPorts `_ and `Homebrew `_ packages are called ``portmidi``. To build documentation locally:: python setup.py docs This requires Sphinx. The resulting files can be found in ``docs/_build/``. Known Bugs ---------- * in OS X, PortMidi and RtMidi usually hang for a second or two seconds while initializing. This is actually not a Mido bug, but something that happens at a lower level. * PortMidi in Ubuntu is mistakenly compiled in debug mode, which causes it to print out error message instead of returning an error code:: PortMidi: `Bad pointer' type ENTER...PortMidi call failed... See https://bugs.launchpad.net/ubuntu/+source/portmidi/+bug/890600 This means here is no way for Mido to catch the error and raise an exception. This regularity occurs in two places: in PortMidi when you close a port that has a callback, and in Pygame when you close any port. Source Code ----------- Latest version of the code: https://github.com/olemb/mido/ . Latest development version: https://github.com/olemb/mido/tree/develop/ License ------- Mido is released under the terms of the `MIT license `_. Contact ------- Ole Martin Bjorndalen - ombdalen@gmail.com mido-1.1.18/setup.cfg0000664000175000017500000000022013002711364014562 0ustar olembolemb00000000000000[wheel] universal = 1 [easy_install] [pytest] norecursedirs = build dist examples [egg_info] tag_build = tag_date = 0 tag_svn_revision = 0 mido-1.1.18/mido.egg-info/0000775000175000017500000000000013002711364015371 5ustar olembolemb00000000000000mido-1.1.18/mido.egg-info/top_level.txt0000664000175000017500000000000513002711364020116 0ustar olembolemb00000000000000mido mido-1.1.18/mido.egg-info/SOURCES.txt0000664000175000017500000000405113002711364017255 0ustar olembolemb00000000000000LICENSE MANIFEST.in README.rst run_tests.py setup.cfg setup.py bin/mido-connect bin/mido-play bin/mido-ports bin/mido-serve docs/Makefile docs/about_midi.rst docs/acknowledgements.rst docs/authors.rst docs/backends.rst docs/bin.rst docs/changes.rst docs/conf.py docs/contributing.rst docs/freezing.rst docs/implementing_backends.rst docs/implementing_ports.rst docs/index.rst docs/installing.rst docs/intro.rst docs/lib.rst docs/license.rst docs/make.bat docs/message_types.rst docs/messages.rst docs/meta_message_types.rst docs/midi_files.rst docs/parsing.rst docs/ports.rst docs/resources.rst docs/socket_ports.rst docs/string_encoding.rst docs/syx.rst docs/_static/PLACEHOLDER docs/images/midi_time.svg examples/using_rtmidi_directly.py examples/backends/printer.py examples/backends/rtm.py examples/backends/rtmidi_python_backend.py examples/backends/use_printer.py examples/midifiles/create_midi_file.py examples/midifiles/play_midi_file.py examples/midifiles/print_midi_file.py examples/midifiles/test.sh examples/ports/input_filter.py examples/ports/list_ports.py examples/ports/multi_receive.py examples/ports/nonblocking_receive.py examples/ports/queue_port.py examples/ports/receive.py examples/ports/send.py examples/sockets/forward_ports.py examples/sockets/serve_ports.py examples/sockets/simple_client.py examples/sockets/simple_server.py extras/README.rst extras/hid_joystick.py mido/__init__.py mido/messages.py mido/parser.py mido/ports.py mido/sockets.py mido/syx.py mido/test_messages.py mido/test_midifiles.py mido/test_midifiles_load.py mido/test_parser.py mido/test_ports.py mido/test_sockets.py mido/test_string_format.py mido/test_syx.py mido.egg-info/PKG-INFO mido.egg-info/SOURCES.txt mido.egg-info/dependency_links.txt mido.egg-info/not-zip-safe mido.egg-info/top_level.txt mido/backends/__init__.py mido/backends/backend.py mido/backends/portmidi.py mido/backends/portmidi_init.py mido/backends/pygame.py mido/backends/rtmidi.py mido/backends/test_backend.py mido/midifiles/__init__.py mido/midifiles/meta.py mido/midifiles/midifiles.py mido/midifiles/tracks.pymido-1.1.18/mido.egg-info/dependency_links.txt0000664000175000017500000000000113002711364021437 0ustar olembolemb00000000000000 mido-1.1.18/mido.egg-info/PKG-INFO0000664000175000017500000001405013002711364016466 0ustar olembolemb00000000000000Metadata-Version: 1.1 Name: mido Version: 1.1.18 Summary: MIDI Objects for Python Home-page: https://mido.readthedocs.io/ Author: Ole Martin Bjorndalen Author-email: ombdalen@gmail.com License: MIT Description: Mido - MIDI Objects for Python ============================== Mido is a library for working with MIDI messages and ports. It's designed to be as straight forward and Pythonic as possible: .. code-block:: python >>> import mido >>> output = mido.open_output() >>> output.send(mido.Message('note_on', note=60, velocity=64)) .. code-block:: python >>> with input as mido.open_input('SH-201'): ... for msg in input: ... print(msg) .. code-block:: python >>> from mido import Message >>> msg = Message('program_change', program=1) >>> msg >>> msg.copy(program=2, time=100) >>> msg.time 100 >>> msg.bytes() [192, 1] .. code-block:: python >>> from mido import MidiFile >>> for msg in MidiFile('song.mid').play(): ... output.send(msg) Full documentation at https://mido.readthedocs.io/ Main Features ------------- * works in Python 2 and 3. * convenient message objects. * supports PortMidi, RtMidi and Pygame. New backends are easy to write. * full support for all 18 messages defined by the MIDI standard. * standard port API allows all kinds of input and output ports to be used interchangeably. New port types can be written by subclassing and overriding a few methods.s * includes a reusable MIDI parser. * full support for MIDI files (read, write, create and play) with complete access to every message in the file, including all common meta messages. * can read and write SYX files (binary and plain text). * implements (somewhat experimental) MIDI over TCP/IP with socket ports. This allows for example wireless MIDI between two computers. * includes programs for playing MIDI files, listing ports and serving and forwarding ports over a network. Status ------ 1.1 is the second stable release. See docs/changes.rst for a full list of changes. Requirements ------------ Mido targets Python 2.7 and 3.2. If you want to use message ports, you will need `PortMidi `_ installed on your system. The PortMidi library is loaded on demand, so you can use the parser and messages without it. The PortMidi wrapper is tested on on Ubuntu and Mac OS X, but may also run on other systems where the ``portmidi.so/dll`` file is available. Alternative backends are included for `python-rtmidi `_ and `Pygame `_. These can be selected with the environment variable ``MIDO_BACKEND`` or by calling ``mido.set_backend()``. Like PortMidi, these are loaded on demand. Installing ---------- To install:: $ pip install mido The PortMidi wrapper is written with `ctypes`, so no compilation is required. If you want to use ports, you need the PortMidi shared library. The Ubuntu package is called ``libportmidi-dev``, while the `MacPorts `_ and `Homebrew `_ packages are called ``portmidi``. To build documentation locally:: python setup.py docs This requires Sphinx. The resulting files can be found in ``docs/_build/``. Known Bugs ---------- * in OS X, PortMidi and RtMidi usually hang for a second or two seconds while initializing. This is actually not a Mido bug, but something that happens at a lower level. * PortMidi in Ubuntu is mistakenly compiled in debug mode, which causes it to print out error message instead of returning an error code:: PortMidi: `Bad pointer' type ENTER...PortMidi call failed... See https://bugs.launchpad.net/ubuntu/+source/portmidi/+bug/890600 This means here is no way for Mido to catch the error and raise an exception. This regularity occurs in two places: in PortMidi when you close a port that has a callback, and in Pygame when you close any port. Source Code ----------- Latest version of the code: https://github.com/olemb/mido/ . Latest development version: https://github.com/olemb/mido/tree/develop/ License ------- Mido is released under the terms of the `MIT license `_. Contact ------- Ole Martin Bjorndalen - ombdalen@gmail.com Platform: UNKNOWN Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Developers Classifier: Natural Language :: English Classifier: License :: OSI Approved :: MIT License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3.2 mido-1.1.18/mido.egg-info/not-zip-safe0000664000175000017500000000000113002711176017620 0ustar olembolemb00000000000000 mido-1.1.18/bin/0000775000175000017500000000000013002711364013517 5ustar olembolemb00000000000000mido-1.1.18/bin/mido-connect0000775000175000017500000000153112775440354016042 0ustar olembolemb00000000000000#!/usr/bin/env python """ Forward all messages from one or more ports to server. """ import argparse import mido def parse_args(): parser = argparse.ArgumentParser(description=__doc__) arg = parser.add_argument arg('address', metavar='ADDRESS', help='host:port to connect to') arg('ports', metavar='PORT', nargs='+', help='input ports to listen to') return parser.parse_args() args = parse_args() try: hostname, port = mido.sockets.parse_address(args.address) ports = [mido.open_input(name) for name in args.ports] with mido.sockets.connect(hostname, port) as server_port: print('Connected.') for message in mido.ports.multi_receive(ports): print('Sending {}'.format(message)) server_port.send(message) except KeyboardInterrupt: pass mido-1.1.18/bin/mido-play0000775000175000017500000000434713002711347015351 0ustar olembolemb00000000000000#!/usr/bin/env python """ Play MIDI file on output port. Example: mido-play some_file.mid Todo: - add option for printing messages """ from __future__ import print_function, division import sys import argparse import mido from mido import MidiFile, Message, tempo2bpm def parse_args(): parser = argparse.ArgumentParser(description=__doc__) arg = parser.add_argument arg('-o', '--output-port', help='Mido port to send output to') arg('-m', '--print-messages', dest='print_messages', action='store_true', default=False, help='Print messages as they are played back') arg('-q', '--quiet', dest='quiet', action='store_true', default=False, help='print nothing') arg('files', metavar='FILE', nargs='+', help='MIDI file to play') return parser.parse_args() def play_file(output, filename, print_messages): midi_file = MidiFile(filename) print('Playing {}.'.format(midi_file.filename)) length = midi_file.length print('Song length: {} minutes, {} seconds.'.format( int(length / 60), int(length % 60))) print('Tracks:') for i, track in enumerate(midi_file.tracks): print(' {:2d}: {!r}'.format(i, track.name.strip())) for message in midi_file.play(meta_messages=True): if print_messages: sys.stdout.write(repr(message) + '\n') sys.stdout.flush() if isinstance(message, Message): output.send(message) elif message.type == 'set_tempo': print('Tempo changed to {:.1f} BPM.'.format( tempo2bpm(message.tempo))) print() def main(): try: with mido.open_output(args.output_port) as output: print('Using output {!r}.'.format(output.name)) output.reset() try: for filename in args.files: play_file(output, filename, args.print_messages) finally: print() output.reset() except KeyboardInterrupt: pass args = parse_args() if args.quiet: def print(*args): pass main() mido-1.1.18/bin/mido-ports0000775000175000017500000000137612775440354015567 0ustar olembolemb00000000000000#!/usr/bin/env python """ List available PortMidi ports. """ from __future__ import print_function import os import sys import mido def print_ports(heading, port_names): print(heading) for name in port_names: print(" '{}'".format(name)) print() print() print_ports('Available input Ports:', mido.get_input_names()) print_ports('Available output Ports:', mido.get_output_names()) for name in ['MIDO_DEAFULT_INPUT', 'MIDO_DEFAULT_OUTPUT', 'MIDO_DEFAULT_IOPORT', 'MIDO_BACKEND']: try: value = os.environ[name] print('{}={!r}'.format(name, value)) except LookupError: print('{} not set.'.format(name)) print() print('Using backend {}.'.format(mido.backend.name)) print() mido-1.1.18/bin/mido-serve0000775000175000017500000000162412775440354015540 0ustar olembolemb00000000000000#!/usr/bin/env python """ Serve one or more output ports. Every message received on any of the connected sockets will be sent to every output port. """ import argparse import mido from mido import sockets from mido.ports import MultiPort def parse_args(): parser = argparse.ArgumentParser(description=__doc__) arg = parser.add_argument arg('address', metavar='ADDRESS', help='host:port to serve on') arg('ports', metavar='PORT', nargs='+', help='output port to serve') return parser.parse_args() args = parse_args() try: out = MultiPort([mido.open_output(name) for name in args.ports]) (hostname, port) = sockets.parse_address(args.address) with sockets.PortServer(hostname, port) as server: for message in server: print('Received {}'.format(message)) out.send(message) except KeyboardInterrupt: pass mido-1.1.18/extras/0000775000175000017500000000000013002711364014255 5ustar olembolemb00000000000000mido-1.1.18/extras/hid_joystick.py0000664000175000017500000001443212775440355017335 0ustar olembolemb00000000000000import struct import select """ Init: 8 = init? Time stamp | (ms since boot) | --+--+--+-- | -- Button number f0 fb 37 09 00 00 81 00 f0 fb 37 09 00 00 81 01 f0 fb 37 09 00 00 81 02 f0 fb 37 09 00 00 81 03 f0 fb 37 09 00 00 81 04 f0 fb 37 09 00 00 81 05 f0 fb 37 09 00 00 81 06 f0 fb 37 09 00 00 81 07 f0 fb 37 09 00 00 81 08 f0 fb 37 09 00 00 81 09 f0 fb 37 09 00 00 81 0a f0 fb 37 09 00 00 81 0b f0 fb 37 09 00 00 82 00 f0 fb 37 09 00 00 82 01 f0 fb 37 09 00 00 82 02 f0 fb 37 09 00 00 82 03 f0 fb 37 09 00 00 82 04 f0 fb 37 09 00 00 82 05 --+-- | | 1 = button, 2 = | value (little endian unsigned) button down | 98 f0 2f 09 01 00 01 00 1 down 08 fa 2f 09 00 00 01 00 1 up 2c 6a 31 09 01 00 01 01 2 down 04 73 31 09 00 00 01 01 2 up 48 bf 32 09 01 00 01 02 3 down f8 c4 32 09 00 00 01 02 3 up Logitech PS2-style gamepad: axis 0 == left stick -left / right (left is negative) axis 1 == left stick -up / down (up is negative) axis 2 == right stick -left / right axis 3 == right stick -up / down axis 4 == plus stick -left / right (when mode is off), values min/0/max axis 5 == plus stick -up / down (when mode is off, values min/0/max The + stick has two modes. When the mode light is off, it sends axis 4/5. When mode is on, it sends axis 0/1. The values are -32767, 0, and 32767. Other axis have values from -32767 to 32767 as well. """ JS_EVENT_BUTTON = 0x1 JS_EVENT_AXIS = 0x2 JS_EVENT_INIT = 0x80 def read_event(device): data = device.read(8) event = {} (event['time'], event['value'], event['type'], event['number']) = struct.unpack('IhBB', data) event['init'] = bool(event['type'] & JS_EVENT_INIT) event['type'] &= 0x7f # Strip away the flag bits (JS_EVENT_INIT etc.) if event['type'] != JS_EVENT_BUTTON: event['normalized_value'] = \ float(event['value']) / 0x7fff # Normalize to -1..1 event['type'] = {1: 'button', 2: 'axis'}[event['type']] return event def read_events(device_name): with open(device_name, 'rb') as device: while True: yield read_event(device) def panic(port): """ Send "All Notes Off" and "Reset All Controllers" on all channels. """ for channel in range(16): for control in [121, 123]: message = mido.Message('control_change', channel=channel, control=control, value=0) print(message) port.send(message) class Monophonic: # Todo: this assumes everything is on channel 0! def __init__(self, output, channel=0): self.output = output self.notes = set() self.current_note = None self.channel = channel def send(self, message): if message.type not in ['note_on', 'note_off'] or \ message.channel != self.channel: self.output.send(message) return if message.type == 'note_on': self.notes.add(message.note) elif message.type == 'note_off': if message.note in self.notes: self.notes.remove(message.note) print(self.notes) try: note = min(self.notes) except ValueError: note = None if note == self.current_note: return # Same note as before, no change. if self.current_note is not None: off = mido.Message('note_off', note=self.current_note, velocity=message.velocity) print(off) self.output.send(off) self.current_note = None if note is not None: on = mido.Message('note_on', note=note, velocity=message.velocity) print(on) self.output.send(on) self.current_note = note def play_scale(dev, out): # out = Monophonic(out, channel=0) # Major scale. scale = [0, 2, 4, 5, 7, 9, 11, 12, 14, 16, 17, 19] # program = 16 # Organ program = 74 out.send(mido.Message('program_change', program=program)) while True: event = read_event(dev) if event['init']: continue # Skip init events. if event['type'] == 'button': # Convert to D-major scale starting at middle D. note = 62 + 12 + scale[event['number']] if event['value']: type_ = 'note_on' else: type_ = 'note_off' message = mido.Message(type_, note=note, velocity=64) out.send(message) # elif event['type'] == 'axis': # if event['number'] == 0: # pitch_scale = mido.messages.MAX_PITCHWHEEL # pitch = int(event['normalized_value'] * pitch_scale) # out.send(mido.Message('pitchwheel', pitch=pitch)) def play_drums(dev, out): # http://www.midi.org/techspecs/gm1sound.php note_mapping = { 2: 35, # Acoustic Bass Drum 6: 38, # Acoustic Snare 1: 41, # Low Floor Tom 4: 47, # Low Mid Tom 3: 50, # High Tom 8: 51, # Ride Cymbal 5: 42, # Closed Hi Hat 7: 46, # Open Hi Hat 9: 52, # Chinese Cymbal 10: 55, # Splash Cymbal } while True: event = read_event(dev) if event['init']: continue if event['type'] == 'button': print(event) button = event['number'] + 1 # Number buttons starting with 1. if button not in note_mapping: continue if event['value']: type_ = 'note_on' else: type_ = 'note_off' note = note_mapping[button] message = mido.Message(type_, channel=9, note=note, velocity=64) print(message) out.send(message) if __name__ == '__main__': import sys import mido with open('/dev/input/js0') as dev: with mido.open_output('SD-20 Part A') as out: try: # play_drums(dev, out) play_scale(dev, out) finally: panic(out) mido-1.1.18/extras/README.rst0000664000175000017500000000042712775440355015766 0ustar olembolemb00000000000000Disclaimer =========== These are experimental versions of functionality that may be rolled into Mido some time in the future. Until the, proceed at your own risk. (Where risk means the danger the code will crash or that the API will change once you had just gotten used to it.) mido-1.1.18/examples/0000775000175000017500000000000013002711364014565 5ustar olembolemb00000000000000mido-1.1.18/examples/midifiles/0000775000175000017500000000000013002711364016532 5ustar olembolemb00000000000000mido-1.1.18/examples/midifiles/test.sh0000775000175000017500000000020712775440355020066 0ustar olembolemb00000000000000#!/bin/bash function play { # mido-play test.mid pmidi -p 20:0 -d 0 test.mid } ./create_midi_file.py && xxd test.mid && play mido-1.1.18/examples/midifiles/print_midi_file.py0000775000175000017500000000070413002656226022252 0ustar olembolemb00000000000000#!/usr/bin/env python """ Open a MIDI file and print every message in every track. Support for MIDI files is still experimental. """ import sys from mido import MidiFile if __name__ == '__main__': filename = sys.argv[1] midi_file = MidiFile(filename) for i, track in enumerate(midi_file.tracks): sys.stdout.write('=== Track {}\n'.format(i)) for message in track: sys.stdout.write(' {!r}\n'.format(message)) mido-1.1.18/examples/midifiles/create_midi_file.py0000775000175000017500000000106513002656226022362 0ustar olembolemb00000000000000#!/usr/bin/env python """ Create a new MIDI file with some random notes. The file is saved to test.mid. """ import random from mido import Message, MidiFile, MidiTrack notes = [64, 64+7, 64+12] outfile = MidiFile() track = MidiTrack() outfile.tracks.append(track) track.append(Message('program_change', program=12)) delta = 16 for i in range(4): note = random.choice(notes) track.append(Message('note_on', note=note, velocity=100, time=delta)) track.append(Message('note_off', note=note, velocity=100, time=delta)) outfile.save('test.mid') mido-1.1.18/examples/midifiles/play_midi_file.py0000775000175000017500000000112513002656226022061 0ustar olembolemb00000000000000#!/usr/bin/env python """ Play MIDI file on output port. Run with (for example): ./play_midi_file.py 'SH-201 MIDI 1' 'test.mid' """ import sys import mido from mido import MidiFile filename = sys.argv[1] if len(sys.argv) == 3: portname = sys.argv[2] else: portname = None with mido.open_output(portname) as output: try: for message in MidiFile(filename).play(): print(message) output.send(message) except KeyboardInterrupt: print() output.reset() mido-1.1.18/examples/backends/0000775000175000017500000000000013002711364016337 5ustar olembolemb00000000000000mido-1.1.18/examples/backends/rtmidi_python_backend.py0000664000175000017500000000714413002656226023264 0ustar olembolemb00000000000000"""Backend for rtmidi-python: https://pypi.python.org/pypi/rtmidi-python To use this backend copy (or link) it to somewhere in your Python path and call: mido.set_backend('rtmidi_python_backend') or set shell variable $MIDO_BACKEND to rtmidi_python_backend: Todo: * add support for APIs. * active_sensing is still filtered. (The same is true for mido.backends.rtmidi.)There may be a way to remove this filtering. """ from __future__ import absolute_import import os import time from Queue import Queue import rtmidi_python as rtmidi # Todo: change this to a relative import if the backend is included in # the package. from mido.ports import BaseInput, BaseOutput def get_devices(api=None, **kwargs): devices = [] input_names = set(rtmidi.MidiIn().ports) output_names = set(rtmidi.MidiOut().ports) for name in sorted(input_names | output_names): devices.append({ 'name': name, 'is_input': name in input_names, 'is_output': name in output_names, }) return devices class PortCommon(object): def _open(self, api=None, virtual=False, **kwargs): self._queue = Queue() # rtapi = _get_api_id(api) opening_input = hasattr(self, 'receive') if opening_input: self._rt = rtmidi.MidiIn(api) self._rt.ignore_types(False, False, True) self.callback = kwargs.get('callback') else: self._rt = rtmidi.MidiOut() # rtapi=rtapi) # Turn of ignore of sysex, time and active_sensing. ports = self._rt.ports if virtual: if self.name is None: raise IOError('virtual port must have a name') self._rt.open_virtual_port(self.name) else: if self.name is None: # Todo: this could fail if list is empty. # In RtMidi, the default port is the first port. try: self.name = ports[0] except IndexError: raise IOError('no ports available') try: port_id = ports.index(self.name) except ValueError: raise IOError('unknown port {!r}'.format(self.name)) try: self._rt.open_port(port_id) except RuntimeError as err: raise IOError(*err.args) # api = _api_to_name[self._rt.get_current_api()] api = '' self._device_type = 'RtMidi/{}'.format(api) if virtual: self._device_type = 'virtual {}'.format(self._device_type) @property def callback(self): return self._rt._callback @callback.setter def callback(self, func): self._rt.callback = func def _callback_wrapper(self, *args, **kw): asodosaid self._parser.feed(message_data[0]) for message in self._parser: if self.callback: self.callback(message) def _close(self): self._rt.close_port() del self._rt # Virtual ports are closed when this is deleted. class Input(PortCommon, BaseInput): def _receive(self, block=True): # Since there is no blocking read in RtMidi, the block # flag is ignored and the enclosing receive() takes care # of blocking. while True: message_data, timestamp = self._rt.get_message() if message_data is None: break else: self._parser.feed(message_data) class Output(PortCommon, BaseOutput): def _send(self, message): self._rt.send_message(message.bytes()) mido-1.1.18/examples/backends/use_printer.py0000664000175000017500000000104612775440355021270 0ustar olembolemb00000000000000""" Try out the new printer port backend. It also works with MIDO_BACKEND, so you can do: $ MIDO_BACKEND=printer python >>> import mido >>> mido.get_output_names() ['The Printer Port'] """ import time import mido mido.set_backend('printer') print('Available outputs: {!r}'.format(mido.get_output_names())) with mido.open_output() as port: print('Using {}.'.format(port)) port.send(mido.Message('program_change', program=10)) for i in [1, 2, 3]: port.send(mido.Message('control_change', control=1, value=i)) mido-1.1.18/examples/backends/rtm.py0000664000175000017500000000606212775440355017536 0ustar olembolemb00000000000000""" Experimental backend for rtmidi-python: http://github.com/superquadratic/rtmidi-python - Doesn't work with Python 3.3: File "rtmidi_python.pyx", line 61, in rtmidi_python.MidiIn.__cinit__ (rtmidi_ python.cpp:1214) TypeError: expected bytes, str found - Virtual ports don't show up, so other programs can't connect to them. - There is no way to select API. Other than that, it works exactly like the included python-rtmidi backend. """ from __future__ import absolute_import import os import time import mido import rtmidi_python as rtmidi from mido.ports import BaseInput, BaseOutput def get_devices(): devices = [] input_names = set(rtmidi.MidiIn().ports) output_names = set(rtmidi.MidiOut().ports) for name in sorted(input_names | output_names): devices.append({ 'name' : name, 'is_input' : name in input_names, 'is_output' : name in output_names, }) return devices class PortCommon(object): def _open(self, virtual=False, callback=None): opening_input = hasattr(self, 'receive') if opening_input: self._rt = rtmidi.MidiIn() self._rt.ignore_types(False, False, False) if callback: def callback_wrapper(message, delta_time): self._parser.feed(message) for message in self._parser: callback(message) self._rt.callback = self._callback = callback_wrapper self._has_callback = True else: self._has_callback = False else: self._rt = rtmidi.MidiOut() # Turn of ignore of sysex, time and active_sensing. ports = self._rt.ports if virtual: if self.name is None: raise IOError('virtual port must have a name') self._rt.open_virtual_port(self.name) else: if self.name is None: # Todo: this could fail if list is empty. # In RtMidi, the default port is the first port. try: self.name = ports[0] except IndexError: raise IOError('no ports available') try: port_id = ports.index(self.name) except ValueError: raise IOError('unknown port {!r}'.format(self.name)) self._rt.open_port(port_id) self._device_type = 'rtmidi_python' def _close(self): self._rt.close_port() class Input(PortCommon, BaseInput): # Todo: sysex messages do not arrive here. def _receive(self, block=True): if self._has_callback: raise IOError('a callback is currently set for this port') while True: (message, delta_time) = self._rt.get_message() if message is None: break else: self._parser.feed(message) class Output(PortCommon, BaseOutput): def _send(self, message): self._rt.send_message(message.bytes()) mido-1.1.18/examples/backends/printer.py0000664000175000017500000000107512775440355020416 0ustar olembolemb00000000000000""" A simple custom backend with an output port type which prints messages to stdout. """ from mido.ports import BaseOutput def get_devices(): return [{'name': 'The Print Port', 'is_input': False, 'is_output': True}] class Output(BaseOutput): def _open(self, **kwargs): device = get_devices()[0] if self.name is None: self.name = device['name'] elif self.name != device['name']: raise ValueError('unknown port {!r}'.format(self.name)) def _send(self, message): print(message) mido-1.1.18/examples/using_rtmidi_directly.py0000664000175000017500000000124312775440355021552 0ustar olembolemb00000000000000""" First example from here modified to use Mido messages: http://pypi.python.org/pypi/python-rtmidi/ """ import time import mido import rtmidi midiout = rtmidi.MidiOut() available_ports = midiout.get_ports() if available_ports: midiout.open_port(0) else: midiout.open_virtual_port("My virtual output") # Original example: # note_on = [0x99, 60, 112] # channel 10, middle C, velocity 112 # note_off = [0x89, 60, 0] note_on = mido.Message('note_on', channel=9, note=60, velocity=112).bytes() note_off = mido.Message('note_off', channel=9, note=60, velocity=0).bytes() midiout.send_message(note_on) time.sleep(0.5) midiout.send_message(note_off) del midiout mido-1.1.18/examples/sockets/0000775000175000017500000000000013002711364016240 5ustar olembolemb00000000000000mido-1.1.18/examples/sockets/forward_ports.py0000775000175000017500000000076412775440355021536 0ustar olembolemb00000000000000#!/usr/bin/env python """ Forward all messages from one or more ports to server. Example: python forward_ports.py localhost:8080 'Keyboard MIDI 1' """ import sys import mido host, port = mido.sockets.parse_address(sys.argv[1]) ports = [mido.open_input(name) for name in sys.argv[2:]] with mido.sockets.connect(host, port) as server_port: print('Connected.') for message in mido.ports.multi_receive(ports): print('Sending {}'.format(message)) server_port.send(message) mido-1.1.18/examples/sockets/simple_client.py0000775000175000017500000000160412775440355021464 0ustar olembolemb00000000000000#!/usr/bin/env python """ Simple client that sends program_change messages to server at timed intervals. Example: python simple_client.py localhost:8080 """ import sys import time import random import mido if sys.argv[1:]: address = sys.argv[1] else: address = 'localhost:9080' host, port = mido.sockets.parse_address(address) notes = [60, 67, 72, 79, 84, 79, 72, 67, 60] on = mido.Message('note_on', velocity=100) off = mido.Message('note_off', velocity=100) base = random.randrange(12) print('Connecting to {}'.format(address)) with mido.sockets.connect(host, port) as server_port: try: message = mido.Message('program_change') for note in notes: on.note = off.note = base + note server_port.send(on) time.sleep(0.05) server_port.send(off) time.sleep(0.1) finally: server_port.reset() mido-1.1.18/examples/sockets/simple_server.py0000775000175000017500000000106112775440355021511 0ustar olembolemb00000000000000#!/usr/bin/env python """ Simple server that just prints every message it receives. python simple_server.py localhost:8080 """ import sys import time import mido from mido import sockets from mido.ports import MultiPort if sys.argv[1:]: address = sys.argv[1] else: address = 'localhost:9080' try: (hostname, portno) = sockets.parse_address(address) print('Serving on {}'.format(address)) with sockets.PortServer(hostname, portno) as server: for message in server: print(message) except KeyboardInterrupt: pass mido-1.1.18/examples/sockets/serve_ports.py0000775000175000017500000000146612775440355021216 0ustar olembolemb00000000000000#!/usr/bin/env python """ Serve one or more output ports. Every message received on any of the connected sockets will be sent to every output port. Example: python serve_ports.py :8080 'SH-201' 'SD-20 Part A' This simply iterates through all incoming messages. More advanced and flexible servers can be written by calling the ``accept()`` and ``accept(block=False) methods directly. See PortServer.__init__() for an example. """ import sys import mido from mido import sockets from mido.ports import MultiPort # Todo: do this with a argument parser. out = MultiPort([mido.open_output(name) for name in sys.argv[2:]]) (host, port) = sockets.parse_address(sys.argv[1]) with sockets.PortServer(host, port) as server: for message in server: print('Received {}'.format(message)) out.send(message) mido-1.1.18/examples/ports/0000775000175000017500000000000013002711364015734 5ustar olembolemb00000000000000mido-1.1.18/examples/ports/input_filter.py0000775000175000017500000000153712775440355021042 0ustar olembolemb00000000000000#!/usr/bin/env python """ Receive messages on the input port and print messages with a specific channel (defaults to 0). Usage: python example_input_filter.py portname [CHANNEL] [...] """ from __future__ import print_function import sys import mido def accept_notes(port): """Only let note_on and note_off messages through.""" for message in port: if message.type in ('note_on', 'note_off'): yield message if len(sys.argv) > 1: portname = sys.argv[1] else: portname = None # Use default port try: with mido.open_input(portname) as port: print('Using {}'.format(port)) print("Ignoring everything but 'note_on' and 'note_off'.") print('Waiting for notes...') for message in accept_notes(port): print('Received {}'.format(message)) except KeyboardInterrupt: pass mido-1.1.18/examples/ports/send.py0000775000175000017500000000150612775440355017263 0ustar olembolemb00000000000000#!/usr/bin/env python """ Send random notes to the output port. """ from __future__ import print_function import sys import time import random import mido from mido import Message if len(sys.argv) > 1: portname = sys.argv[1] else: portname = None # Use default port # A pentatonic scale notes = [60, 62, 64, 67, 69, 72] try: with mido.open_output(portname, autoreset=True) as port: print('Using {}'.format(port)) while True: note = random.choice(notes) on = Message('note_on', note=note) print('Sending {}'.format(on)) port.send(on) time.sleep(0.05) off = Message('note_off', note=note) print('Sending {}'.format(off)) port.send(off) time.sleep(0.1) except KeyboardInterrupt: pass print() mido-1.1.18/examples/ports/queue_port.py0000775000175000017500000000236413002656226020513 0ustar olembolemb00000000000000#!/usr/bin/env python """ Queue port for threading. """ import sys PY2 = (sys.version_info.major == 2) if PY2: from Queue import Queue, Empty else: from queue import Queue, Empty from threading import Thread import time import random from mido import Message from mido.ports import BaseInput, BaseOutput PY2 = (sys.version_info.major == 2) class QueuePort(BaseInput, BaseOutput): def _open(self, **kwargs): maxsize = kwargs.get('maxsize', 0) self._queue = Queue(maxsize) def _send(self, message): self._queue.put(message) # We need to override receive() since _receive() is not # allowed to return a message directly. def receive(self, block=True): try: return self._queue.get(block=block) except Empty: return None def _get_device_type(self): return 'queue' if __name__ == '__main__': def program_changer(): while True: queue_port.send( Message('program_change', program=random.randrange(128))) time.sleep(0.2) queue_port = QueuePort(maxsize=3) thread = Thread(target=program_changer) thread.daemon = True thread.start() for message in queue_port: print(message) mido-1.1.18/examples/ports/multi_receive.py0000775000175000017500000000065412775440355021171 0ustar olembolemb00000000000000#!/usr/bin/env python """ Receive messages from multiple ports. """ import mido from mido.ports import multi_receive # Open all available inputs. ports = [mido.open_input(name) for name in mido.get_input_names()] for port in ports: print('Using {}'.format(port)) print('Waiting for messages...') try: for message in multi_receive(ports): print('Received {}'.format(message)) except KeyboardInterrupt: pass mido-1.1.18/examples/ports/receive.py0000775000175000017500000000100613002656226017735 0ustar olembolemb00000000000000#!/usr/bin/env python """ Receive messages from the input port and print them out. """ from __future__ import print_function import sys import mido if len(sys.argv) > 1: portname = sys.argv[1] else: portname = None # Use default port try: with mido.open_input(portname) as port: print('Using {}'.format(port)) print('Waiting for messages...') for message in port: print('Received {}'.format(message)) sys.stdout.flush() except KeyboardInterrupt: pass mido-1.1.18/examples/ports/nonblocking_receive.py0000775000175000017500000000111612775440355022334 0ustar olembolemb00000000000000#!/usr/bin/env python """ Example of non-blocking reception from input port. """ from __future__ import print_function import sys import time import mido if len(sys.argv) > 1: portname = sys.argv[1] else: portname = None # Use default port try: with mido.open_input(portname) as port: print('Using {}'.format(port)) while True: for message in port.iter_pending(): print('Received {}'.format(message)) print('Doing something else for a while...') time.sleep(0.5) except KeyboardInterrupt: pass mido-1.1.18/examples/ports/list_ports.py0000775000175000017500000000056712775440355020542 0ustar olembolemb00000000000000#!/usr/bin/env python """ List available PortMidi ports. """ from __future__ import print_function import sys import mido def print_ports(heading, port_names): print(heading) for name in port_names: print(" '{}'".format(name)) print() print() print_ports('Input Ports:', mido.get_input_names()) print_ports('Output Ports:', mido.get_output_names()) mido-1.1.18/mido/0000775000175000017500000000000013002711364013677 5ustar olembolemb00000000000000mido-1.1.18/mido/midifiles/0000775000175000017500000000000013002711364015644 5ustar olembolemb00000000000000mido-1.1.18/mido/midifiles/tracks.py0000664000175000017500000000614213002711347017511 0ustar olembolemb00000000000000from .meta import MetaMessage class MidiTrack(list): @property def name(self): """Name of the track. This will return the name from the first track_name meta message in the track, or '' if there is no such message. Setting this property will update the name field of the first track_name message in the track. If no such message is found, one will be added to the beginning of the track with a delta time of 0.""" for message in self: if message.type == 'track_name': return message.name else: return u'' @name.setter def name(self, name): # Find the first track_name message and modify it. for message in self: if message.type == 'track_name': message.name = name return else: # No track name found, add one. self.insert(0, MetaMessage('track_name', name=name, time=0)) def copy(self): return self.__class__(self) def __getitem__(self, index_or_slice): # Retrieve item from the MidiTrack lst = list.__getitem__(self, index_or_slice) if isinstance(index_or_slice, int): # If an index was provided, return the list element return lst else: # Otherwise, construct a MidiTrack to return. # Todo: this make a copy of the list. Is there a better way? return self.__class__(lst) def __add__(self, other): return self.__class__(list.__add__(self, other)) def __mul__(self, other): return self.__class__(list.__mul__(self, other)) def __repr__(self): return ''.format(self.name, len(self)) def _to_abstime(messages): """Convert messages to absolute time.""" now = 0 for msg in messages: now += msg.time yield msg.copy(time=now) def _to_reltime(messages): """Convert messages to relative time.""" now = 0 for msg in messages: delta = msg.time - now yield msg.copy(time=delta) now = msg.time def fix_end_of_track(messages): """Remove all end_of_track messages and add one at the end. This is used by merge_tracks() and MidiFile.save().""" # Accumulated delta time from removed end of track messages. # This is added to the next message. accum = 0 for msg in messages: if msg.type == 'end_of_track': accum += msg.time else: if accum: delta = accum + msg.time yield msg.copy(time=delta) accum = 0 else: yield msg yield MetaMessage('end_of_track', time=accum) def merge_tracks(tracks): """Returns a MidiTrack object with all messages from all tracks. The messages are returned in playback order with delta times as if they were all in one track. """ messages = [] for track in tracks: messages.extend(_to_abstime(track)) messages.sort(key=lambda msg: msg.time) return MidiTrack(fix_end_of_track(_to_reltime(messages))) mido-1.1.18/mido/midifiles/midifiles.py0000664000175000017500000003121113002711347020162 0ustar olembolemb00000000000000""" MIDI file reading and playback. References: http://home.roadrunner.com/~jgglatt/ http://home.roadrunner.com/~jgglatt/tech/miditech.htm http://home.roadrunner.com/~jgglatt/tech/midifile.htm http://www.sonicspot.com/guide/midifiles.html http://www.ccarh.org/courses/253/assignment/midifile/ https://code.google.com/p/binasc/wiki/mainpage http://stackoverflow.com/questions/2984608/midi-delta-time http://www.recordingblogs.com/sa/tabid/82/EntryId/44/MIDI-Part-XIII-Delta-time-a http://www.sonicspot.com/guide/midifiles.html """ from __future__ import print_function, division import io import sys import time import string import struct from ..messages import build_message, Message, get_spec from .meta import MetaMessage, build_meta_message, meta_charset from .meta import MetaSpec, add_meta_spec, encode_variable_int from .tracks import MidiTrack, merge_tracks, fix_end_of_track PY2 = (sys.version_info.major == 2) # The default tempo is 120 BPM. # (500000 microseconds per beat (quarter note).) DEFAULT_TEMPO = 500000 DEFAULT_TICKS_PER_BEAT = 480 def print_byte(byte, pos=0): char = chr(byte) if char.isspace() or not char in string.printable: char = '.' print(' {:06x}: {:02x} {}'.format(pos, byte, char)) class DebugFileWrapper(object): def __init__(self, file): self.file = file def read(self, size): data = self.file.read(size) for byte in data: print_byte(byte, self.file.tell()) return data def tell(self): return self.file.tell() def read_byte(self): byte = self.read(1) if byte == b'': raise EOFError else: return ord(byte) def read_bytes(infile, size): return [read_byte(infile) for _ in range(size)] def _dbg(text=''): print(text) # We can't use the chunk module for two reasons: # # 1. we may have mixed big and little endian chunk sizes. (RIFF is # little endian while MTrk is big endian.) # # 2. the chunk module assumes that chunks are padded to the neares # multiple of 2. This is not true of MIDI files. def read_chunk_header(infile): header = infile.read(8) if len(header) < 8: raise EOFError # Todo: check for b'RIFF' and switch endian? return struct.unpack('>4sL', header) def read_file_header(infile): name, size = read_chunk_header(infile) if name != b'MThd': raise IOError('MThd not found. Probably not a MIDI file') else: data = infile.read(size) if len(data) < 6: raise EOFError return struct.unpack('>hhh', data[:6]) def read_message(infile, status_byte, peek_data, delta): try: spec = get_spec(status_byte) except LookupError: raise IOError('undefined status byte 0x{:02x}'.format(status_byte)) # Subtrac 1 for status byte. size = spec.length - 1 - len(peek_data) data_bytes = peek_data + read_bytes(infile, size) for byte in data_bytes: if byte > 127: raise IOError('data byte must be in range 0..127') return build_message(spec, [status_byte] + data_bytes, time=delta) def read_sysex(infile, delta): length = read_variable_int(infile) data = read_bytes(infile, length) # Strip start and end bytes. # Todo: is this necessary? if data and data[0] == 0xf0: data = data[1:] if data and data[-1] == 0xf7: data = data[:-1] return Message('sysex', data=data, time=delta) def read_variable_int(infile): delta = 0 while True: byte = read_byte(infile) delta = (delta << 7) | (byte & 0x7f) if byte < 0x80: return delta def read_meta_message(infile, delta): type = read_byte(infile) length = read_variable_int(infile) data = read_bytes(infile, length) return build_meta_message(type, data, delta) def read_track(infile, debug=False): track = MidiTrack() name, size = read_chunk_header(infile) if name != b'MTrk': raise IOError('no MTrk header at start of track') if debug: _dbg('-> size={}'.format(size)) _dbg() start = infile.tell() last_status = None while True: # End of track reached. if infile.tell() - start == size: break if debug: _dbg('Message:') delta = read_variable_int(infile) if debug: _dbg('-> delta={}'.format(delta)) # Todo: not all messages have running status status_byte = read_byte(infile) if status_byte < 0x80: if last_status is None: raise IOError('running status without last_status') peek_data = [status_byte] status_byte = last_status else: if status_byte != 0xff: # Meta messages don't set running status. last_status = status_byte peek_data = [] if status_byte == 0xff: msg = read_meta_message(infile, delta) elif status_byte in [0xf0, 0xf7]: # Todo: I'm not quite clear on the difference between # f0 and f7 events. msg = read_sysex(infile, delta) else: msg = read_message(infile, status_byte, peek_data, delta) track.append(msg) if debug: _dbg('-> {!r}'.format(msg)) _dbg() return track def write_chunk(outfile, name, data): """Write an IFF chunk to the file. `name` must be a bytestring.""" outfile.write(name) outfile.write(struct.pack('>L', len(data))) outfile.write(data) def write_track(outfile, track): data = bytearray() running_status_byte = None for msg in fix_end_of_track(track): if not isinstance(msg, MetaMessage): if msg._spec.status_byte >= 0xf8: raise ValueError( ("realtime message '{}' is not " "allowed in a MIDI file".format( message.type))) data.extend(encode_variable_int(msg.time)) if msg.type == 'sysex': running_status_byte = None data.append(0xf0) # length (+ 1 for end byte (0xf7)) data.extend(encode_variable_int(len(msg.data) + 1)) data.extend(msg.data) data.append(0xf7) else: raw = msg.bytes() if (isinstance(msg, Message) and raw[0] < 0xf0 and raw[0] == running_status_byte): data.extend(raw[1:]) else: data.extend(raw) running_status_byte = raw[0] write_chunk(outfile, b'MTrk', data) class MidiFile: def __init__(self, filename=None, file=None, type=1, ticks_per_beat=DEFAULT_TICKS_PER_BEAT, charset='latin1', debug=False): self.filename = filename self.type = type self.ticks_per_beat = ticks_per_beat self.charset = charset self.debug = debug self.tracks = [] if type not in range(3): raise ValueError( 'invalid format {} (must be 0, 1 or 2)'.format(format)) if file is not None: self._load(file) elif self.filename is not None: with io.open(filename, 'rb') as file: self._load(file) def add_track(self, name=None): """Add a new track to the file. This will create a new MidiTrack object and append it to the track list. """ track = MidiTrack() if name is not None: track.name = name self.tracks.append(track) return track def _load(self, infile): if self.debug: infile = DebugFileWrapper(infile) with meta_charset(self.charset): if self.debug: _dbg('Header:') (self.type, num_tracks, self.ticks_per_beat) = read_file_header(infile) if self.debug: _dbg('-> type={}, tracks={}, ticks_per_beat={}'.format( self.type, num_tracks, self.ticks_per_beat)) _dbg() for i in range(num_tracks): if self.debug: _dbg('Track {}:'.format(i)) self.tracks.append(read_track(infile, debug=self.debug)) # Todo: used to ignore EOFError. I hope things still work. @property def length(self): """Playback time in seconds. This will be computed by going through every message in every track and adding up delta times. """ if self.type == 2: raise ValueError('impossible to compute length' ' for type 2 (asynchronous) file') return sum(msg.time for msg in self) def _get_seconds_per_tick(self, tempo): # Tempo is given in microseconds per beat (default 500000). # At this tempo there are (500000 / 1000000) == 0.5 seconds # per beat. At the default resolution of 480 ticks per beat # this is: # # (500000 / 1000000) / 480 == 0.5 / 480 == 0.0010417 # return (tempo / 1000000.0) / self.ticks_per_beat def __iter__(self): # The tracks of type 2 files are not in sync, so they can # not be played back like this. if self.type == 2: raise TypeError("can't merge tracks in type 2 (asynchronous) file") seconds_per_tick = self._get_seconds_per_tick(DEFAULT_TEMPO) for msg in merge_tracks(self.tracks): # Convert message time from absolute time # in ticks to relative time in seconds. if msg.time > 0: delta = msg.time * seconds_per_tick else: delta = 0 yield msg.copy(time=delta) if msg.type == 'set_tempo': seconds_per_tick = self._get_seconds_per_tick(msg.tempo) def play(self, meta_messages=False): """Play back all tracks. The generator will sleep between each message by default. Messages are yielded with correct timing. The time attribute is set to the number of seconds slept since the previous message. By default you will only get normal MIDI messages. Pass meta_messages=True if you also want meta messages. You will receive copies of the original messages, so you can safely modify them without ruining the tracks. """ sleep = time.sleep for msg in self: sleep(msg.time) if isinstance(msg, MetaMessage) and not meta_messages: continue else: yield msg def save(self, filename=None, file=None): """Save to a file. If file is passed the data will be saved to that file. This is typically an in-memory file or and already open file like sys.stdout. If filename is passed the data will be saved to that file. Raises ValueError if both file and filename are None, or if a type 0 file has != one track. """ if self.type == 0 and len(self.tracks) != 1: raise ValueError('type 0 file must have exactly 1 track') if file is not None: self._save(file) elif filename is not None: with io.open(filename, 'wb') as file: self._save(file) else: raise ValueError('requires filename or file') def _save(self, outfile): with meta_charset(self.charset): header = struct.pack('>hhh', self.type, len(self.tracks), self.ticks_per_beat) write_chunk(outfile, b'MThd', header) for track in self.tracks: write_track(outfile, track) def print_tracks(self, meta_only=False): """Prints out all messages in a .midi file. May take argument meta_only to show only meta messages. Use: print_tracks() -> will print all messages print_tracks(meta_only=True) -> will print only MetaMessages """ for i, track in enumerate(self.tracks): print('=== Track {}'.format(i)) for msg in track: if not isinstance(msg, MetaMessage) and meta_only: pass else: print('{!r}'.format(msg)) def __repr__(self): return ''.format( self.filename, self.type, len(self.tracks), sum([len(track) for track in self.tracks])) # The context manager has no purpose but is kept around since it was # used in examples in the past. def __enter__(self): return self def __exit__(self, type, value, traceback): return False mido-1.1.18/mido/midifiles/meta.py0000664000175000017500000003311713002711347017152 0ustar olembolemb00000000000000""" Meta messages for MIDI files. Todo: - what if an unknown meta message is implemented and someone depends on the 'data' attribute? - is 'type_byte' a good name? - 'values' is not a good name for a dictionary. - type and value safety? - copy(). - expose _key_signature_encode/decode? """ from __future__ import print_function, division import sys import math import struct from contextlib import contextmanager from ..messages import BaseMessage, check_time PY2 = (sys.version_info.major == 2) _charset = 'latin1' def reverse_table(table): """Return value: key for dictionary.""" return {value: key for (key, value) in table.items()} _key_signature_decode = { (-7, 0): 'Cb', (-6, 0): 'Gb', (-5, 0): 'Db', (-4, 0): 'Ab', (-3, 0): 'Eb', (-2, 0): 'Bb', (-1, 0): 'F', (0, 0): 'C', (1, 0): 'G', (2, 0): 'D', (3, 0): 'A', (4, 0): 'E', (5, 0): 'B', (6, 0): 'F#', (7, 0): 'C#', (-7, 1): 'Abm', (-6, 1): 'Ebm', (-5, 1): 'Bbm', (-4, 1): 'Fm', (-3, 1): 'Cm', (-2, 1): 'Gm', (-1, 1): 'Dm', (0, 1): 'Am', (1, 1): 'Em', (2, 1): 'Bm', (3, 1): 'F#m', (4, 1): 'C#m', (5, 1): 'G#m', (6, 1): 'D#m', (7, 1): 'A#m', } _key_signature_encode = reverse_table(_key_signature_decode) _smpte_framerate_decode = { 0: 24, 1: 25, 2: 29.97, 3: 30, } _smpte_framerate_encode = reverse_table(_smpte_framerate_decode) def signed(to_type, n): formats = { 'byte': 'Bb', 'short': 'Hh', 'long': 'Ll', 'ubyte': 'bB', 'ushort': 'hH', 'ulong': 'lL', } try: pack_format, unpack_format = formats[to_type] except KeyError: raise ValueError('invalid integer type {}'.format(to_type)) try: packed = struct.pack(pack_format, n) return struct.unpack(unpack_format, packed)[0] except struct.error as err: raise ValueError(*err.args) def unsigned(to_type, n): return signed('u{}'.format(to_type), n) def encode_variable_int(value): """Encode variable length integer. Returns the integer as a list of bytes, where the last byte is < 128. This is used for delta times and meta message payload length. """ if not isinstance(value, int) or value < 0: raise ValueError('variable int must be a positive integer') bytes = [] while value: bytes.append(value & 0x7f) value >>= 7 if bytes: bytes.reverse() # Set high bit in every byte but the last. for i in range(len(bytes) - 1): bytes[i] |= 0x80 return bytes else: return [0] def encode_string(string): return list(bytearray(string.encode(_charset))) def decode_string(data): return bytearray(data).decode(_charset) def bpm2tempo(bpm): """Convert beats per minute to MIDI file tempo. Returns microseconds per beat as an integer:: 240 => 250000 120 => 500000 60 => 1000000 """ # One minute is 60 million microseconds. return int(round((60 * 1000000) / bpm)) def tempo2bpm(tempo): """Convert MIDI file tempo to BPM. Returns BPM as an integer or float:: 250000 => 240 500000 => 120 1000000 => 60 """ # One minute is 60 million microseconds. return (60 * 1000000) / tempo @contextmanager def meta_charset(tmp_charset): global _charset old = _charset _charset = tmp_charset yield _charset = old def check_int(value, low, high): if not isinstance(value, int): raise TypeError('attribute must be an integer') elif not low <= value <= high: raise ValueError('attribute must be in range {}..{}'.format(low, high)) if PY2: def check_str(value): if not isinstance(value, basestring): raise TypeError('attribute must be unicode or string') else: def check_str(value): if not isinstance(value, str): raise TypeError('attribute must a string') class MetaSpec(object): def check(self, name, value): pass class MetaSpec_sequence_number(MetaSpec): type_byte = 0x00 attributes = ['number'] defaults = [0] def decode(self, message, data): message.number = (data[0] << 8) | data[1] def encode(self, message): return [message.number >> 8, message.number & 0xff] def check(self, name, value): check_int(value, 0, 255) class MetaSpec_text(MetaSpec): type_byte = 0x01 attributes = ['text'] defaults = [''] def decode(self, message, data): message.text = decode_string(data) def encode(self, message): return encode_string(message.text) def check(self, name, value): check_str(value) class MetaSpec_copyright(MetaSpec_text): type_byte = 0x02 class MetaSpec_track_name(MetaSpec_text): type_byte = 0x03 attributes = ['name'] defaults = [''] def decode(self, message, data): message.name = decode_string(data) def encode(self, message): return encode_string(message.name) class MetaSpec_instrument_name(MetaSpec_track_name): type_byte = 0x04 class MetaSpec_lyrics(MetaSpec_text): type_byte = 0x05 class MetaSpec_marker(MetaSpec_text): type_byte = 0x06 class MetaSpec_cue_marker(MetaSpec_text): type_byte = 0x07 class MetaSpec_device_name(MetaSpec_track_name): type_byte = 0x09 class MetaSpec_channel_prefix(MetaSpec): type_byte = 0x20 attributes = ['channel'] defaults = [0] def decode(self, message, data): message.channel = data[0] def encode(self, message): return [message.channel] def check(self, name, value): check_int(value, 0, 0xff) class MetaSpec_midi_port(MetaSpec): type_byte = 0x21 attributes = ['port'] defaults = [0] def decode(self, message, data): message.port = data[0] def encode(self, message): return [message.port] def check(self, name, value): check_int(value, 0, 255) class MetaSpec_end_of_track(MetaSpec): type_byte = 0x2f attributes = [] defaults = [] def decode(self, message, data): pass def encode(self, message): return [] class MetaSpec_set_tempo(MetaSpec): type_byte = 0x51 attributes = ['tempo'] defaults = [500000] def decode(self, message, data): message.tempo = (data[0] << 16) | (data[1] << 8) | (data[2]) def encode(self, message): tempo = message.tempo return [tempo >> 16, tempo >> 8 & 0xff, tempo & 0xff] def check(self, name, value): check_int(value, 0, 0xffffff) class MetaSpec_smpte_offset(MetaSpec): type_byte = 0x54 attributes = ['frame_rate', 'hours', 'minutes', 'seconds', 'frames', 'sub_frames' ] # Todo: What are some good defaults? defaults = [24, 0, 0, 0, 0, 0] def decode(self, message, data): message.frame_rate = _smpte_framerate_decode[(data[0] >> 6)] message.hours = (data[0] & 0x3f) message.minutes = data[1] message.seconds = data[2] message.frames = data[3] message.sub_frames = data[4] def encode(self, message): frame_rate_lookup = _smpte_framerate_encode[message.frame_rate] << 6 return [frame_rate_lookup | message.hours, message.minutes, message.seconds, message.frames, message.sub_frames] def check(self, name, value): if name == 'frame_rate': if value not in _smpte_framerate_encode: valid = ', '.join(sorted(_smpte_framerate_encode.keys())) raise ValueError('frame_rate must be one of {}'.format(valid)) elif name == 'hours': check_int(value, 0, 255) elif name in ['minutes', 'seconds']: check_int(value, 0, 59) elif name == 'frames': check_int(value, 0, 255) elif name == 'sub_frames': check_int(value, 0, 99) class MetaSpec_time_signature(MetaSpec): type_byte = 0x58 # Todo: these need more sensible names. attributes = ['numerator', 'denominator', 'clocks_per_click', 'notated_32nd_notes_per_beat'] defaults = [4, 2, 24, 8] def decode(self, message, data): message.numerator = data[0] message.denominator = 2 ** data[1] message.clocks_per_click = data[2] message.notated_32nd_notes_per_beat = data[3] def encode(self, message): return [ message.numerator, int(math.log(message.denominator, 2)), message.clocks_per_click, message.notated_32nd_notes_per_beat, ] def check(self, name, value): if name == 'denominator': # This allows for the ridiculous time signature of # 4/57896044618658097711785492504343953926634... # 992332820282019728792003956564819968 check_int(value, 1, 2 ** 255) encoded = math.log(value, 2) encoded_int = int(encoded) if encoded != encoded_int: raise ValueError('denominator must be a power of 2') else: check_int(value, 0, 255) class MetaSpec_key_signature(MetaSpec): type_byte = 0x59 attributes = ['key'] defaults = ['C'] def decode(self, message, data): key = signed('byte', data[0]) mode = data[1] message.key = _key_signature_decode[(key, mode)] def encode(self, message): key, mode = _key_signature_encode[message.key] return [unsigned('byte', key), mode] def check(self, name, value): if not value in _key_signature_encode: raise ValueError('invalid key {!r}'.format(value)) class MetaSpec_sequencer_specific(MetaSpec): type_byte = 0x7f attributes = ['data'] defaults = [[]] def decode(self, message, data): message.data = tuple(data) def encode(self, message): return list(message.data) _specs = {} def add_meta_spec(klass): spec = klass() if not hasattr(spec, 'type'): name = klass.__name__.replace('MetaSpec_', '') spec.type = name # This is used by copy(). spec.settable_attributes = set(spec.attributes) | {'time'} _specs[spec.type_byte] = spec _specs[spec.type] = spec def _add_builtin_meta_specs(): for name in globals(): if name.startswith('MetaSpec_'): add_meta_spec(globals()[name]) _add_builtin_meta_specs() def build_meta_message(type_, data, delta=0): # Todo: handle unknown type. try: spec = _specs[type_] except KeyError: return UnknownMetaMessage(type_, data) message = MetaMessage(spec, time=delta) spec.decode(message, data) return message class MetaMessage(BaseMessage): def __init__(self, type_, **kwargs): # Todo: allow type_ to be a type byte? # Todo: handle unknown type. if isinstance(type_, MetaSpec): vars(self)['_spec'] = type_ else: vars(self)['_spec'] = _specs[type_] vars(self)['type'] = self._spec.type for name in kwargs: if name == 'time': continue # Time is always allowed. if name not in self._spec.settable_attributes: raise ValueError( '{} is not a valid argument for this message type'.format( name)) for name, value in zip(self._spec.attributes, self._spec.defaults): vars(self)[name] = value vars(self)['time'] = 0 for name, value in kwargs.items(): setattr(self, name, value) def __setattr__(self, name, value): if name in self._spec.settable_attributes: if name == 'time': check_time(value) else: self._spec.check(name, value) vars(self)[name] = value elif name in vars(self): raise AttributeError('{} attribute is read only'.format(name)) else: raise AttributeError( '{} message has no attribute {}'.format(self.type, name)) def bytes(self): data = self._spec.encode(self) return ([0xff, self._spec.type_byte] + encode_variable_int(len(data)) + data) def __repr__(self): attributes = [] for name in self._spec.attributes: attributes.append('{}={!r}'.format(name, getattr(self, name))) attributes = ' '.join(attributes) if attributes: attributes = (' {}'.format(attributes)) return ''.format(self.type, attributes, self.time) class UnknownMetaMessage(MetaMessage): def __init__(self, type_byte, data=None, time=0): if data is None: data = [] self.type = 'unknown_meta' self._type_byte = type_byte self._data = data self.time = time def __repr__(self): return ('').format( self._type_byte, self._data, self.time) # Override all checking. def __setattr__(self, name, value): vars(self)[name] = value def bytes(self): return ([0xff, self._type_byte] + encode_variable_int(len(self._data)) + self._data) mido-1.1.18/mido/midifiles/__init__.py0000664000175000017500000000020013002711347017746 0ustar olembolemb00000000000000from .meta import bpm2tempo, tempo2bpm, MetaMessage from .tracks import MidiTrack, merge_tracks from .midifiles import MidiFile mido-1.1.18/mido/test_parser.py0000664000175000017500000000724112775440355016627 0ustar olembolemb00000000000000from __future__ import print_function import random from pytest import raises from .messages import Message, get_message_specs from .parser import Parser, parse, parse_all def test_parse(): """Parse a note_on msg and compare it to one created with Message().""" parsed = parse(b'\x90\x4c\x20') other = Message('note_on', channel=0, note=0x4c, velocity=0x20) assert parsed == other def test_parse_stray_data(): """The parser should ignore stray data bytes.""" assert parse_all(b'\x20\x30') == [] def test_parse_stray_status_bytes(): """The parser should ignore stray status bytes.""" assert parse_all(b'\x90\x90\xf0') == [] def test_encode_and_parse(): """Encode a message and then parse it. Should return the same message. """ note_on = Message('note_on') assert note_on == parse(note_on.bytes()) def test_encode_and_parse_all(): """Encode and then parse all message types. This checks mostly for errors in the parser. """ parser = Parser() for spec in get_message_specs(): msg = Message(spec.type) parser.feed(msg.bytes()) outmsg = parser.get_message() assert outmsg is not True assert outmsg.type == spec.type def test_feed_byte(): """Put various things into feed_byte().""" parser = Parser() parser.feed_byte(0) parser.feed_byte(255) with raises(TypeError): parser.feed_byte([1, 2, 3]) with raises(ValueError): parser.feed_byte(-1) with raises(ValueError): parser.feed_byte(256) def test_feed(): """Put various things into feed().""" parser = Parser() parser.feed([]) parser.feed([1, 2, 3]) # Todo: add more valid types. with raises(TypeError): parser.feed(1) with raises(TypeError): parser.feed(None) with raises(TypeError): parser.feed() def test_parse_random_bytes(): """Parser should not crash when parsing random data.""" randrange = random.Random('a_random_seed').randrange parser = Parser() for _ in range(10000): byte = randrange(256) parser.feed_byte(byte) def test_running_status(): return # Running doesn't work with PortMidi, so it's turned off. # Two note_on messages. (The second has no status byte, # so the last seen status byte is used instead.) assert (parse_all([0x90, 0x01, 0x02, 0x01, 0x02]) == [Message('note_on', note=1, velocity=2)] * 2) # System common messages should cancel running status. # (0xf3 is 'songpos'. This should be 'song song=2' # followed by a stray data byte. assert parse_all([0xf3, 2, 3]) == [Message('song', song=2)] def test_parse_channel(): """Parser should not discard the channel in channel messages.""" assert parse([0x90, 0x00, 0x00]).channel == 0 assert parse([0x92, 0x00, 0x00]).channel == 2 def test_one_byte_message(): """Messages that are one byte long should not wait for data bytes.""" messages = parse_all([0xf6]) # Tune request. assert len(messages) == 1 assert messages[0].type == 'tune_request' def test_undefined_messages(): """The parser should ignore undefined status bytes and sysex_end.""" messages = parse_all([0xf4, 0xf5, 0xf7, 0xf9, 0xfd]) assert messages == [] def test_realtime_inside_sysex(): """Realtime message inside sysex should be delivered first.""" messages = parse_all([0xf0, 0, 0xfb, 0, 0xf7]) assert len(messages) == 2 assert messages[0].type == 'continue' assert messages[1].type == 'sysex' def test_undefined_realtime_inside_sysex(): """Undefined realtime message inside sysex should ignored.""" messages = parse_all([0xf0, 0, 0xf9, 0xfd, 0, 0xf7]) assert len(messages) == 1 assert messages[0].type == 'sysex' mido-1.1.18/mido/backends/0000775000175000017500000000000013002711364015451 5ustar olembolemb00000000000000mido-1.1.18/mido/backends/backend.py0000664000175000017500000001516613002656226017430 0ustar olembolemb00000000000000import os import importlib from .. import ports DEFAULT_BACKEND = 'mido.backends.portmidi' class Backend(object): """ Wrapper for backend module. A backend module implements classes for input and output ports for a specific MIDI library. The Backend object wraps around the object and provides convenient 'open_*()' and 'get_*_names()' functions. """ def __init__(self, name=None, api=None, load=False, use_environ=True): self.name = name or os.environ.get('MIDO_BACKEND', DEFAULT_BACKEND) self.api = api self.use_environ = use_environ self._module = None # Split out api (if present). if api: self.api = api elif self.name and '/' in self.name: self.name, self.api = self.name.split('/', 1) else: self.api = None if load: self.load() @property def module(self): """A reference module implementing the backend. This will always be a valid reference to a module. Accessing this property will load the module. Use .loaded to check if the module is loaded. """ self.load() return self._module @property def loaded(self): """Return True if the module is loaded.""" return self._module is not None def load(self): """Load the module. Does nothing if the module is already loaded. This function will be called if you access the 'module' property.""" if not self.loaded: self._module = importlib.import_module(self.name) def _env(self, name): if self.use_environ: return os.environ.get(name) else: return None def _add_api(self, kwargs): if self.api and 'api' not in kwargs: kwargs['api'] = self.api return kwargs def open_input(self, name=None, virtual=False, callback=None, **kwargs): """Open an input port. If the environment variable MIDO_DEFAULT_INPUT is set, if will override the default port. virtual=False Passing True opens a new port that other applications can connect to. Raises IOError if not supported by the backend. callback=None A callback function to be called when a new message arrives. The function should take one argument (the message). Raises IOError if not supported by the backend. """ kwargs.update(dict(virtual=virtual, callback=callback)) if name is None: name = self._env('MIDO_DEFAULT_INPUT') return self.module.Input(name, **self._add_api(kwargs)) def open_output(self, name=None, virtual=False, autoreset=False, **kwargs): """Open an output port. If the environment variable MIDO_DEFAULT_OUTPUT is set, if will override the default port. virtual=False Passing True opens a new port that other applications can connect to. Raises IOError if not supported by the backend. autoreset=False Automatically send all_notes_off and reset_all_controllers on all channels. This is the same as calling `port.reset()`. """ kwargs.update(dict(virtual=virtual, autoreset=autoreset)) if name is None: name = self._env('MIDO_DEFAULT_OUTPUT') return self.module.Output(name, **self._add_api(kwargs)) def open_ioport(self, name=None, virtual=False, callback=None, autoreset=False, **kwargs): """Open a port for input and output. If the environment variable MIDO_DEFAULT_IOPORT is set, if will override the default port. virtual=False Passing True opens a new port that other applications can connect to. Raises IOError if not supported by the backend. callback=None A callback function to be called when a new message arrives. The function should take one argument (the message). Raises IOError if not supported by the backend. autoreset=False Automatically send all_notes_off and reset_all_controllers on all channels. This is the same as calling `port.reset()`. """ kwargs.update(dict(virtual=virtual, callback=callback, autoreset=autoreset)) if name is None: name = self._env('MIDO_DEFAULT_IOPORT') or None if hasattr(self.module, 'IOPort'): # Backend has a native IOPort. Use it. return self.module.IOPort(name, **self._add_api(kwargs)) else: # Backend has no native IOPort. Use the IOPort wrapper # in midi.ports. # # We need an input and an output name. # MIDO_DEFAULT_IOPORT overrides the other two variables. if name: input_name = output_name = name else: input_name = self._env('MIDO_DEFAULT_INPUT') output_name = self._env('MIDO_DEFAULT_OUTPUT') kwargs = self._add_api(kwargs) return ports.IOPort(self.module.Input(input_name, **kwargs), self.module.Output(output_name, **kwargs)) def _get_devices(self, **kwargs): if hasattr(self.module, 'get_devices'): return self.module.get_devices(**self._add_api(kwargs)) else: return [] def get_input_names(self, **kwargs): """Return a sorted list of all input port names.""" devices = self._get_devices(**self._add_api(kwargs)) names = [device['name'] for device in devices if device['is_input']] return list(sorted(names)) def get_output_names(self, **kwargs): """Return a sorted list of all output port names.""" devices = self._get_devices(**self._add_api(kwargs)) names = [device['name'] for device in devices if device['is_output']] return list(sorted(names)) def get_ioport_names(self, **kwargs): """Return a sorted list of all I/O port names.""" devices = self._get_devices(**self._add_api(kwargs)) inputs = [device['name'] for device in devices if device['is_input']] outputs = [device['name'] for device in devices if device['is_output']] return sorted(set(inputs) & set(outputs)) def __repr__(self): if self.loaded: status = 'loaded' else: status = 'not loaded' if self.api: name = '{}/{}'.format(self.name, self.api) else: name = self.name return ''.format(name, status) mido-1.1.18/mido/backends/portmidi.py0000664000175000017500000002151512775440355017675 0ustar olembolemb00000000000000""" Input and Output ports for PortMidi. There is no need to use this module directly. All you need is available in the toplevel module. PortMidi documentation: http://portmedia.sourceforge.net/portmidi/doxygen/ """ import time import threading from ..parser import Parser from ..messages import Message from ..ports import BaseInput, BaseOutput, sleep from . import portmidi_init as pm _state = {'port_count': 0} def _refresh_port_list(): if _state['port_count'] == 0: # If no ports are open we can reboot PortMidi # to refresh the port list. This is a hack, but it's # the only way to get an up-to-date list. pm.lib.Pm_Terminate() pm.lib.Pm_Initialize() def _check_error(return_value): """Raise IOError if return_value < 0. The exception will be raised with the error message from PortMidi. """ if return_value == pm.pmHostError: raise IOError('PortMidi Host Error: {}'.format(pm.get_host_error_message())) elif return_value < 0: raise IOError(pm.lib.Pm_GetErrorText(return_value)) def _get_device(device_id): device = {} info_pointer = pm.lib.Pm_GetDeviceInfo(device_id) if not info_pointer: raise IOError('PortMidi device with id={} not found'.format( device_id)) info = info_pointer.contents return { 'id': device_id, 'interface': info.interface.decode('utf-8'), 'name': info.name.decode('utf-8'), 'is_input': info.is_input, 'is_output': info.is_output, 'opened': bool(info.opened), } def _get_default_device(get_input): if get_input: device_id = pm.lib.Pm_GetDefaultInputDeviceID() else: device_id = pm.lib.Pm_GetDefaultOutputDeviceID() if device_id < 0: raise IOError('no default port found') return _get_device(device_id) def _get_named_device(name, get_input): # Look for the device by name and type (input / output) for device in get_devices(): if device['name'] != name: continue # Skip if device is the wrong type if get_input: if device['is_output']: continue else: if device['is_input']: continue if device['opened']: raise IOError('port already opened: {!r}'.format(name)) return device else: raise IOError('unknown port {!r}'.format(name)) def get_devices(**kwargs): """Return a list of devices as dictionaries.""" _refresh_port_list() return [_get_device(i) for i in range(pm.lib.Pm_CountDevices())] class PortCommon(object): """ Mixin with common things for input and output ports. """ def _open(self, **kwargs): _refresh_port_list() if kwargs.get('virtual'): raise ValueError('virtual ports are not supported' ' by the PortMidi backend') self._stream = pm.PortMidiStreamPtr() opening_input = hasattr(self, 'receive') if self.name is None: device = _get_default_device(opening_input) self.name = device['name'] else: device = _get_named_device(self.name, opening_input) if device['opened']: if opening_input: devtype = 'input' else: devtype = 'output' raise IOError('{} port {!r} is already open'.format(devtype, self.name)) if opening_input: _check_error(pm.lib.Pm_OpenInput( pm.byref(self._stream), device['id'], # Input device pm.null, # Input driver info 1000, # Buffer size pm.NullTimeProcPtr, # Time callback pm.null)) # Time info else: _check_error(pm.lib.Pm_OpenOutput( pm.byref(self._stream), device['id'], # Output device pm.null, # Output diver info 0, # Buffer size # (ignored when latency == 0?) pm.NullTimeProcPtr, # Default to internal clock pm.null, # Time info 0)) # Latency # This is set when we return, but the callback thread needs # it to be False now (or it will just return right away.) self.closed = False _state['port_count'] += 1 if opening_input: self._thread = None self.callback = kwargs.get('callback') self._device_type = 'PortMidi/{}'.format(device['interface']) def _close(self): self.callback = None _check_error(pm.lib.Pm_Close(self._stream)) _state['port_count'] -= 1 class Input(PortCommon, BaseInput): """ PortMidi Input port """ def _receive(self, block=True): # Since there is no blocking read in PortMidi, the block # flag is ignored and the enclosing receive() takes care # of blocking. # Allocate buffer. # I get hanging notes if MAX_EVENTS > 1, so I'll have to # resort to calling Pm_Read() in a loop until there are no # more pending events. max_events = 1 BufferType = pm.PmEvent * max_events read_buffer = BufferType() # Read available data from the stream and feed it to the parser. while pm.lib.Pm_Poll(self._stream): # Todo: this should be allocated once # Read one message. Should return 1. # If num_events < 0, an error occured. length = 1 # Buffer length num_events = pm.lib.Pm_Read(self._stream, read_buffer, length) _check_error(num_events) # Get the event event = read_buffer[0] # print('Received: {:x}'.format(event.message)) # The bytes of the message are stored like this: # 0x00201090 -> (0x90, 0x10, 0x10) # (Todo: not sure if this is correct.) packed_message = event.message & 0xffffffff for i in range(4): byte = packed_message & 0xff self._parser.feed_byte(byte) packed_message >>= 8 @property def callback(self): return self._callback @callback.setter def callback(self, func): self._callback = func if func is None: self._stop_thread() else: self._start_thread() def _start_thread(self): """Start callback thread if not already running.""" if not self._thread: self._stop_event = None self._thread = threading.Thread( target=self._thread_main) self._thread.daemon = True self._thread.start() def _stop_thread(self): """Stop callback thread if running.""" if self._thread: # Ask callback thread to stop. self._stop_event = threading.Event() self._stop_event.wait() self._thread = None def _thread_main(self): # Todo: exceptions do not propagate to the main thread, so if # something goes wrong here there is no way to detect it, and # there is no warning. (An unknown variable, for example, will # just make the thread stop silently.) # Receive messages from port until it's closed # or some exception occurs. try: while not self._stop_event: self._receive() for message in self._parser: if self.callback: self.callback(message) sleep() finally: # Inform parent thread that we are done. if self._stop_event: self._stop_event.set() def _close(self): self._stop_thread() PortCommon._close(self) class Output(PortCommon, BaseOutput): """ PortMidi output port """ def _send(self, message): if message.type == 'sysex': # Sysex messages are written as a string. string = pm.c_char_p(bytes(message.bin())) timestamp = 0 # Ignored when latency = 0 _check_error(pm.lib.Pm_WriteSysEx(self._stream, timestamp, string)) else: # The bytes of a message as packed into a 32 bit integer. packed_message = 0 for byte in reversed(message.bytes()): packed_message <<= 8 packed_message |= byte timestamp = 0 # Ignored when latency = 0 _check_error(pm.lib.Pm_WriteShort(self._stream, timestamp, packed_message)) mido-1.1.18/mido/backends/test_backend.py0000664000175000017500000000042413002656226020456 0ustar olembolemb00000000000000from pytest import raises from .backend import Backend def test_split_api(): backend = Backend('test') assert backend.name == 'test' assert backend.api is None backend = Backend('test/ALSA') assert backend.name == 'test' assert backend.api == 'ALSA' mido-1.1.18/mido/backends/rtmidi.py0000664000175000017500000001311113002656226017315 0ustar olembolemb00000000000000""" Backend for python-rtmidi: http://pypi.python.org/pypi/python-rtmidi/ """ from __future__ import absolute_import import os import sys import time PY2 = (sys.version_info.major == 2) if PY2: import Queue as queue else: import queue import rtmidi from ..ports import get_sleep_time, BaseInput, BaseOutput def _get_api_lookup(): api_to_name = {} name_to_api = {} for name in dir(rtmidi): if name.startswith('API_'): value = getattr(rtmidi, name) name = name.replace('API_', '') name_to_api[name] = value api_to_name[value] = name return api_to_name, name_to_api _api_to_name, _name_to_api = _get_api_lookup() def _get_api_id(name=None): if name is None: return rtmidi.API_UNSPECIFIED try: api = _name_to_api[name] except KeyError: raise ValueError('unknown API {}'.format(name)) if name in get_api_names(): return api else: raise ValueError('API {} not compiled in'.format(name)) def get_devices(api=None, **kwargs): devices = [] rtapi = _get_api_id(api) input_names = set(rtmidi.MidiIn(rtapi=rtapi).get_ports()) output_names = set(rtmidi.MidiOut(rtapi=rtapi).get_ports()) for name in sorted(input_names | output_names): devices.append({ 'name': name, 'is_input': name in input_names, 'is_output': name in output_names, }) return devices def get_api_names(): return [_api_to_name[n] for n in rtmidi.get_compiled_api()] class PortCommon(object): def _open(self, api=None, virtual=False, **kwargs): rtapi = _get_api_id(api) opening_input = hasattr(self, 'receive') if opening_input: self._rt = rtmidi.MidiIn(rtapi=rtapi) self._rt.ignore_types(False, False, True) self._queue = queue.Queue() self.callback = kwargs.get('callback') else: self._rt = rtmidi.MidiOut(rtapi=rtapi) # Turn of ignore of sysex, time and active_sensing. ports = self._rt.get_ports() if virtual: if self.name is None: raise IOError('virtual port must have a name') self._rt.open_virtual_port(self.name) else: if self.name is None: # Todo: this could fail if list is empty. # In RtMidi, the default port is the first port. try: self.name = ports[0] except IndexError: raise IOError('no ports available') try: port_id = ports.index(self.name) except ValueError: raise IOError('unknown port {!r}'.format(self.name)) try: self._rt.open_port(port_id) except RuntimeError as err: raise IOError(*err.args) api = _api_to_name[self._rt.get_current_api()] self._device_type = 'RtMidi/{}'.format(api) if virtual: self._device_type = 'virtual {}'.format(self._device_type) def _close(self): self._rt.close_port() del self._rt # Virtual ports are closed when this is deleted. class Input(PortCommon, BaseInput): @property def callback(self): return self._callback @callback.setter def callback(self, func): self._rt.cancel_callback() if func: # First send all queued messages to the callback. while True: try: func(self._queue.get_nowait()) except queue.Empty: break if func is None: self._rt.set_callback(self._feed_queue) self._callback = None else: self._rt.set_callback(self._feed_callback) self._callback = func def _feed_queue(self, message_data, data): self._parser.feed(message_data[0]) for message in self._parser: self._queue.put(message) def _feed_callback(self, message_data, data): self._parser.feed(message_data[0]) for message in self._parser: self._callback(message) # receive() implementation: # # We need to override receive() here because _receive() doesn't allow # us to return a messages directly and putting it in self._messages is # not an option. # # Todo: add doc strings. if PY2: # In Python 2 queue.get() doesn't respond to CTRL-C. A workaroud is # to call queue.get(timeout=100) (very high timeout) in a loop, but all # that does is poll with a timeout of 50 milliseconds. This results in # much too high latency. # # It's better to do our own polling with a shorter sleep time. # # See Issue #49 and https://bugs.python.org/issue8844 def receive(self, block=True): sleep_time = get_sleep_time() while True: try: return self._queue.get_nowait() except queue.Empty: if block: time.sleep(sleep_time) continue else: return None else: def receive(self, block=True): try: return self._queue.get(block=block) except queue.Empty: return None receive.__doc__ = BaseInput.receive.__doc__ def pending(self): return self._queue.qsize() class Output(PortCommon, BaseOutput): def _send(self, message): self._rt.send_message(message.bytes()) mido-1.1.18/mido/backends/pygame.py0000664000175000017500000000706512775440355017334 0ustar olembolemb00000000000000""" Mido ports for pygame.midi. Pygame uses PortMidi, so this is perhaps not very useful. http://www.pygame.org/docs/ref/midi.html """ from __future__ import absolute_import from pygame import midi from ..ports import BaseInput, BaseOutput def _get_device(device_id): keys = ['interface', 'name', 'is_input', 'is_output', 'opened'] info = dict(zip(keys, midi.get_device_info(device_id))) info['id'] = device_id info['name'] = info['name'].decode('utf-8') # Todo: correct encoding? return info def _get_default_device(get_input): if get_input: device_id = midi.get_default_input_id() else: device_id = midi.get_default_output_id() if device_id < 0: raise IOError('no default port found') return _get_device(device_id) def _get_named_device(name, get_input): # Look for the device by name and type (input / output) for device in get_devices(): if device['name'] != name: continue # Skip if device is the wrong type if get_input: if device['is_output']: continue else: if device['is_input']: continue if device['opened']: raise IOError('port already opened: {!r}'.format(name)) return device else: raise IOError('unknown port: {!r}'.format(name)) def get_devices(**kwargs): midi.init() return [_get_device(device_id) for device_id in range(midi.get_count())] class PortCommon(object): """ Mixin with common things for input and output ports. """ def _open(self, **kwargs): if kwargs.get('virtual'): raise ValueError('virtual ports are not supported' ' by the Pygame backend') elif kwargs.get('callback'): raise ValueError('callbacks are not supported' ' by the Pygame backend') midi.init() opening_input = hasattr(self, 'receive') if self.name is None: device = _get_default_device(opening_input) self.name = device['name'] else: device = _get_named_device(self.name, opening_input) if device['opened']: if opening_input: devtype = 'input' else: devtype = 'output' raise IOError('{} port {!r} is already open'.format(devtype, self.name)) if opening_input: self._port = midi.Input(device['id']) else: self._port = midi.Output(device['id']) self._device_type = 'Pygame/{}'.format(device['interface']) def _close(self): self._port.close() class Input(PortCommon, BaseInput): """ PortMidi Input port """ def _receive(self, block=True): # I get hanging notes if MAX_EVENTS > 1, so I'll have to # resort to calling Pm_Read() in a loop until there are no # more pending events. while self._port.poll(): bytes, time = self._port.read(1)[0] if bytes[0] == 0xf0: # Sysex support is broken. # Only the first 3 data bytes arrive. # It's best to ignore these. continue self._parser.feed(bytes) class Output(PortCommon, BaseOutput): """ PortMidi output port """ def _send(self, message): if message.type == 'sysex': self._port.write_sys_ex(midi.time(), message.bytes()) else: self._port.write_short(*message.bytes()) mido-1.1.18/mido/backends/portmidi_init.py0000664000175000017500000000777412775440355020733 0ustar olembolemb00000000000000""" Low-level wrapper for PortMidi library Copied straight from Grant Yoshida's portmidizero, with slight modifications. """ import sys import array from ctypes import * dll_name = '' if sys.platform == 'darwin': dll_name = 'libportmidi.dylib' elif sys.platform in ('win32', 'cygwin'): dll_name = 'portmidi.dll' else: dll_name = 'libportmidi.so' lib = CDLL(dll_name) null = None false = 0 true = 1 # portmidi.h # From portmidi.h PM_HOST_ERROR_MSG_LEN = 256 def get_host_error_message(): """Return host error message.""" buf = create_string_buffer(PM_HOST_ERROR_MSG_LEN) lib.Pm_GetHostErrorText(buf, PM_HOST_ERROR_MSG_LEN) return buf.raw.decode().rstrip('\0') PmError = c_int # PmError enum pmNoError = 0 pmHostError = -10000 pmInvalidDeviceId = -9999 pmInsufficientMemory = -9989 pmBufferTooSmall = -9979 pmBufferOverflow = -9969 pmBadPtr = -9959 pmBadData = -9994 pmInternalError = -9993 pmBufferMaxSize = -9992 lib.Pm_Initialize.restype = PmError lib.Pm_Terminate.restype = PmError PmDeviceID = c_int PortMidiStreamPtr = c_void_p PmStreamPtr = PortMidiStreamPtr PortMidiStreamPtrPtr = POINTER(PortMidiStreamPtr) lib.Pm_HasHostError.restype = c_int lib.Pm_HasHostError.argtypes = [PortMidiStreamPtr] lib.Pm_GetErrorText.restype = c_char_p lib.Pm_GetErrorText.argtypes = [PmError] lib.Pm_GetHostErrorText.argtypes = [c_char_p, c_uint] pmNoDevice = -1 class PmDeviceInfo(Structure): _fields_ = [("structVersion", c_int), ("interface", c_char_p), ("name", c_char_p), ("is_input", c_int), ("is_output", c_int), ("opened", c_int)] PmDeviceInfoPtr = POINTER(PmDeviceInfo) lib.Pm_CountDevices.restype = c_int lib.Pm_GetDefaultOutputDeviceID.restype = PmDeviceID lib.Pm_GetDefaultInputDeviceID.restype = PmDeviceID PmTimestamp = c_long PmTimeProcPtr = CFUNCTYPE(PmTimestamp, c_void_p) NullTimeProcPtr = cast(null, PmTimeProcPtr) # PmBefore is not defined lib.Pm_GetDeviceInfo.argtypes = [PmDeviceID] lib.Pm_GetDeviceInfo.restype = PmDeviceInfoPtr lib.Pm_OpenInput.restype = PmError lib.Pm_OpenInput.argtypes = [PortMidiStreamPtrPtr, PmDeviceID, c_void_p, c_long, PmTimeProcPtr, c_void_p] lib.Pm_OpenOutput.restype = PmError lib.Pm_OpenOutput.argtypes = [PortMidiStreamPtrPtr, PmDeviceID, c_void_p, c_long, PmTimeProcPtr, c_void_p, c_long] lib.Pm_SetFilter.restype = PmError lib.Pm_SetFilter.argtypes = [PortMidiStreamPtr, c_long] lib.Pm_SetChannelMask.restype = PmError lib.Pm_SetChannelMask.argtypes = [PortMidiStreamPtr, c_int] lib.Pm_Abort.restype = PmError lib.Pm_Abort.argtypes = [PortMidiStreamPtr] lib.Pm_Close.restype = PmError lib.Pm_Close.argtypes = [PortMidiStreamPtr] PmMessage = c_long class PmEvent(Structure): _fields_ = [("message", PmMessage), ("timestamp", PmTimestamp)] PmEventPtr = POINTER(PmEvent) lib.Pm_Read.restype = PmError lib.Pm_Read.argtypes = [PortMidiStreamPtr, PmEventPtr, c_long] lib.Pm_Poll.restype = PmError lib.Pm_Poll.argtypes = [PortMidiStreamPtr] lib.Pm_Write.restype = PmError lib.Pm_Write.argtypes = [PortMidiStreamPtr, PmEventPtr, c_long] lib.Pm_WriteShort.restype = PmError lib.Pm_WriteShort.argtypes = [PortMidiStreamPtr, PmTimestamp, c_long] lib.Pm_WriteSysEx.restype = PmError lib.Pm_WriteSysEx.argtypes = [PortMidiStreamPtr, PmTimestamp, c_char_p] # porttime.h # PtError enum PtError = c_int ptNoError = 0 ptHostError = -10000 ptAlreadyStarted = -9999 ptAlreadyStopped = -9998 ptInsufficientMemory = -9997 PtTimestamp = c_long PtCallback = CFUNCTYPE(PmTimestamp, c_void_p) lib.Pt_Start.restype = PtError lib.Pt_Start.argtypes = [c_int, PtCallback, c_void_p] lib.Pt_Stop.restype = PtError lib.Pt_Started.restype = c_int lib.Pt_Time.restype = PtTimestamp mido-1.1.18/mido/backends/__init__.py0000664000175000017500000000000012775440355017567 0ustar olembolemb00000000000000mido-1.1.18/mido/test_messages.py0000664000175000017500000001473713002711347017134 0ustar olembolemb00000000000000import sys from pytest import raises from .messages import Message, check_time, get_spec from .messages import MIN_PITCHWHEEL, MAX_PITCHWHEEL from .parser import Parser, parse, parse_all PY2 = (sys.version_info.major == 2) def test_msg_equality(): args = dict(type='note_on', channel=1, note=2, velocity=3) assert Message(**args) == Message(**args) assert Message(time=1, **args) != Message(time=2, **args) def test_set_type(): with raises(AttributeError): Message('note_on').type = 'note_off' def test_pitchwheel(): """Check if pitchwheel type check and encoding is working.""" msg = Message('pitchwheel', pitch=MIN_PITCHWHEEL) bytes = msg.bytes() assert bytes[1] == bytes[2] msg = Message('pitchwheel', pitch=MAX_PITCHWHEEL) bytes = msg.bytes() assert bytes[1] == bytes[2] == 127 def test_pitchwheel_encode_parse(): """Encode and parse pitchwheel with value=0.""" wheel = Message('pitchwheel', pitch=0) assert wheel == parse(wheel.bytes()) def test_quarter_frame_encode_parse(): """Encode and parse quarter_frame.""" frame = Message('quarter_frame', frame_type=1, frame_value=2) assert frame == parse(frame.bytes()) def test_sysex(): sysex = Message('sysex', data=(1, 2, 3, 4, 5)) assert sysex == parse(sysex.bytes()) def test_check_time(): check_time(1) check_time(1.5) if PY2: # long should be allowed. (It doesn't exist in Python3, # so there's no need to check for it here.) check_time(long('9829389283L')) with raises(TypeError): check_time(None) with raises(TypeError): check_time('abc') with raises(TypeError): check_time(None) with raises(TypeError): check_time('abc') def test_check_channel(): from .messages import check_channel check_channel(0) check_channel(15) with raises(TypeError): check_channel(None) with raises(TypeError): check_channel('abc') with raises(TypeError): check_channel(0.5) with raises(ValueError): check_channel(-1) with raises(ValueError): check_channel(16) def test_check_pos(): from .messages import check_pos, MIN_SONGPOS, MAX_SONGPOS check_pos(0) check_pos(MIN_SONGPOS) check_pos(MAX_SONGPOS) with raises(TypeError): check_pos(None) with raises(TypeError): check_pos('abc') with raises(ValueError): check_pos(MIN_SONGPOS - 1) with raises(ValueError): check_pos(MAX_SONGPOS + 1) def test_check_pitch(): from .messages import check_pitch, MIN_PITCHWHEEL, MAX_PITCHWHEEL # Pitchwheel pitch check_pitch(MIN_PITCHWHEEL) check_pitch(MAX_PITCHWHEEL) with raises(TypeError): check_pitch(None) with raises(TypeError): check_pitch(0.5) with raises(TypeError): check_pitch('abc') with raises(ValueError): check_pitch(MIN_PITCHWHEEL - 1) with raises(ValueError): check_pitch(MAX_PITCHWHEEL + 1) def test_check_data(): from .messages import check_data # check_data() should return the data as a tuple. assert type(check_data([0, 1, 2]) == tuple) assert check_data([0, 1, 2]) == (0, 1, 2) assert check_data(i for i in [1, 2, 3]) == (1, 2, 3) with raises(TypeError): check_data(1) with raises(TypeError): check_data(('a', 'b', 'c')) with raises(ValueError): check_data((-1, -2, -3)) def test_check_frame_type(): from .messages import check_frame_type # Qarter frame type check_frame_type(0) check_frame_type(7) with raises(TypeError): check_frame_type(None) with raises(TypeError): check_frame_type(0.5) with raises(ValueError): check_frame_type(-1) with raises(ValueError): check_frame_type(8) def test_check_databyte(): from .messages import check_databyte # Data byte check_databyte(0) check_databyte(15) with raises(TypeError): check_databyte(None) with raises(TypeError): check_databyte(0.5) with raises(ValueError): check_databyte(-1) with raises(ValueError): check_databyte(128) def test_encode_channel(): from .messages import encode_channel # Channel should be ignored, and an empty list returned. # Thus, there is no reason to check for TypeError # and ValueError. assert encode_channel(channel=0) == [] def test_encode_data(): from .messages import encode_data # Note: encode_data() includes the sysex end byte (0xf7) to avoid a # special case in bytes(). assert encode_data([1, 2, 3]) == [1, 2, 3, 0xf7] def test_encode_(): from .messages import encode_pitch, MIN_PITCHWHEEL, MAX_PITCHWHEEL # Pitchwheel pitch assert encode_pitch(MIN_PITCHWHEEL) == [0, 0] assert encode_pitch(MAX_PITCHWHEEL) == [127, 127] assert encode_pitch(0) == [0, 64] def test_encode_pos(): from .messages import encode_pos, MIN_SONGPOS, MAX_SONGPOS assert encode_pos(MIN_SONGPOS) == [0, 0] assert encode_pos(MAX_SONGPOS) == [127, 127] # Check endian assert [16, 78] == encode_pos(10000) def test_get_spec(): from .messages import get_spec assert get_spec('note_on').type == 'note_on' assert get_spec(0x80).type == 'note_off' assert get_spec(0x82).type == 'note_off' with raises(LookupError): get_spec(-1) with raises(LookupError): get_spec(0) with raises(LookupError): get_spec('banana') def test_sysex_data_type(): """Is messages.data turned into a tuple?""" data = range(1) message = Message('sysex') message.data = data assert isinstance(message.data, tuple) message = Message('sysex', data=data) assert isinstance(message.data, tuple) a = Message('sysex', data=(1, 2)) b = parse(a.bytes()) assert isinstance(b.data, tuple) def test_copy(): orig = Message('note_on', note=22, time=123) copy = orig.copy() assert orig == copy assert orig.time == copy.time assert vars(orig) == vars(copy) copy = orig.copy(velocity=1) orig.velocity = 1 assert orig == copy def test_copy_invalid_attribute(): orig = Message('note_on') valid_spec = get_spec('note_on') # Pass arguments with invalid names. with raises(ValueError): orig.copy(_spec=valid_spec) with raises(ValueError): orig.copy(type='continue') with raises(ValueError): orig.copy(banana=1) # Valid arguments should pass. orig.copy(note=0, velocity=0, time=0) def test_set_invalid_attribute(): """Set an attribute that is not settable.""" valid_spec = get_spec('note_on') msg = Message('note_on') with raises(AttributeError): msg._spec = valid_spec with raises(AttributeError): msg.type = 'continue' with raises(AttributeError): msg.invalid = 'banana' mido-1.1.18/mido/sockets.py0000664000175000017500000001073713002711347015735 0ustar olembolemb00000000000000""" MIDI over TCP/IP. """ import sys import time import socket import select from collections import deque from .parser import Parser from .ports import MultiPort, BaseIOPort, multi_iter_pending, sleep PY2 = (sys.version_info.major == 2) def _is_readable(socket): """Return True if there is data to be read on the socket.""" timeout = 0 (rlist, wlist, elist) = select.select( [socket.fileno()], [], [], timeout) return bool(rlist) class PortServer(MultiPort): # Todo: queue size. def __init__(self, host, portno, backlog=1): MultiPort.__init__(self, format_address(host, portno)) self.ports = [] self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) self._socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, True) self._socket.setblocking(True) self._socket.bind((host, portno)) self._socket.listen(backlog) def _get_device_type(self): return 'server' def _close(self): # Close all connections. for port in self.ports: port.close() self._socket.close() def _update_ports(self): """Remove closed port ports.""" self.ports = [port for port in self.ports if not port.closed] def accept(self, block=True): """ Accept a connection from a client. Will block until there is a new connection, and then return a SocketPort object. If block=False, None will be returned if there is no new connection waiting. """ if not block and not _is_readable(self._socket): return None self._update_ports() conn, (host, port) = self._socket.accept() return SocketPort(host, port, conn=conn) def _send(self, message): self._update_ports() return MultiPort._send(self, message) def _receive(self, block=True): port = self.accept(block=False) if port: self.ports.append(port) self._update_ports() return MultiPort._receive(self) class SocketPort(BaseIOPort): def __init__(self, host, portno, conn=None): self.name = format_address(host, portno) self.closed = False self._parser = Parser() self._messages = self._parser.messages if conn is None: self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) self._socket.setblocking(True) self._socket.connect((host, portno)) else: self._socket = conn if PY2: kwargs = {'bufsize': 0} else: kwargs = {'buffering': None} self._rfile = self._socket.makefile('rb', **kwargs) self._wfile = self._socket.makefile('wb', **kwargs) def _get_device_type(self): return 'socket' def _receive(self, block=True): while _is_readable(self._socket): try: byte = self._rfile.read(1) except socket.error as err: raise IOError(err.args[1]) if byte == '': # The other end has disconnected. self.close() break else: self._parser.feed_byte(ord(byte)) def _send(self, message): try: self._wfile.write(message.bin()) self._wfile.flush() except socket.error as err: if err.errno == 32: # Broken pipe. The other end has disconnected. self.close() raise IOError(err.args[1]) def _close(self): self._socket.close() def connect(host, portno): """Connect to a socket port server. The return value is a SocketPort object connected to another SocketPort object at the server end. Messages can be sent either way. """ return SocketPort(host, portno) def parse_address(address): """Parse and address on the format host:port. Returns a tuple (host, port). Raises ValueError if format is invalid or port is not an integer or out of range. """ words = address.split(':') if len(words) != 2: raise ValueError('address must contain exactly one colon') host, port = words try: port = int(port) except ValueError: raise ValueError('port number must be an integer') # Note: port 0 is not allowed. if not 0 < port < (2**16): raise ValueError('port number out of range') return (host, port) def format_address(host, portno): return '{}{:d}'.format(host, portno) mido-1.1.18/mido/syx.py0000664000175000017500000000354013002711347015077 0ustar olembolemb00000000000000""" Read and write SYX file format """ from __future__ import print_function import re import string import binascii from .messages import Message from .parser import Parser, parse_all _HEXDIGITS = set(string.hexdigits.encode('ascii')) def read_syx_file(filename): """Read sysex messages from SYX file. Returns a list of sysex messages. This handles both the text (hexadecimal) and binary formats. Messages other than sysex will be ignored. Raises ValueError if file is plain text and byte is not a 2-digit hex number. """ def raise_value_error(): raise ValueError('{!r} line {}: invalid hex byte {!r}'.format( filename, lineno, byte)) with open(filename, 'rb') as infile: data = infile.read() if len(data) == 0: # Empty file. return [] # data[0] will give a byte string in Python 2 and an integer in # Python 3. if data[0] in (b'\xf0', 240): # Binary. return parse_all(data) else: # Hex. # We're decoding as latin1 to avoid decoding errors. data = bytearray.fromhex(data.decode('latin1')) return [msg for msg in Parser(data) if msg.type == 'sysex'] def write_syx_file(filename, messages, plaintext=False): """Write sysex messages to a SYX file. Messages other than sysex will be skipped. By default this will write the binary format. Pass ``plaintext=True`` to write the plain text format (hex encoded ASCII text). """ messages = [m for m in messages if m.type == 'sysex'] if plaintext: with open(filename, 'wt') as outfile: for message in messages: outfile.write(message.hex()) outfile.write('\n') else: with open(filename, 'wb') as outfile: for message in messages: outfile.write(message.bin()) mido-1.1.18/mido/ports.py0000664000175000017500000003017113002711347015423 0ustar olembolemb00000000000000""" Useful tools for working with ports Module content: multi_receive -- receive messages from multiple ports IOPort -- combined input / output port. Wraps around to normal ports MessageBuffer -- pseudo-port that stores messages in a deque """ from __future__ import unicode_literals import threading import time import random from collections import deque from .parser import Parser from .messages import Message # How many seconds to sleep before polling again. _DEFAULT_SLEEP_TIME = 0.001 _sleep_time = _DEFAULT_SLEEP_TIME # Todo: document this more. def sleep(): """Sleep for N seconds. This is used in ports when polling and waiting for messages. N can be set with set_sleep_time().""" time.sleep(_sleep_time) def set_sleep_time(seconds=_DEFAULT_SLEEP_TIME): """Set the number of seconds sleep() will sleep.""" global _sleep_time _sleep_time = seconds def get_sleep_time(): """Get number of seconds sleep() will sleep.""" return _sleep_time class BasePort(object): """ Abstract base class for Input and Output ports. """ def __init__(self, name=None, **kwargs): self.name = name self._lock = threading.RLock() self.closed = True self._open(**kwargs) self.closed = False def _open(self, **kwargs): pass def _close(self): pass def close(self): """Close the port. If the port is already closed, nothing will happen. The port is automatically closed when the object goes out of scope or is garbage collected. """ with self._lock: if not self.closed: if hasattr(self, 'autoreset') and self.autoreset: try: self.reset() except IOError: pass self._close() self.closed = True def __del__(self): self.close() def __enter__(self): return self def __exit__(self, type, value, traceback): self.close() return False def __repr__(self): if self.closed: state = 'closed' else: state = 'open' capabilities = (hasattr(self, 'receive'), hasattr(self, 'send')) port_type = { (True, False): 'input', (False, True): 'output', (True, True): 'I/O', (False, False): 'mute', }[capabilities] name = self.name or '' try: device_type = self._device_type except AttributeError: device_type = self.__class__.__name__ return '<{} {} {!r} ({})>'.format( state, port_type, name, device_type) class BaseInput(BasePort): """Base class for input port. Subclass and override _receive() to create a new input port type. (See portmidi.py for an example of how to do this.) """ def __init__(self, name='', **kwargs): """Create an input port. name is the port name, as returned by input_names(). If name is not passed, the default input is used instead. """ BasePort.__init__(self, name, **kwargs) self._parser = Parser() self._messages = self._parser.messages # Shortcut. def _check_callback(self): if hasattr(self, 'callback') and self.callback is not None: raise ValueError('a callback is set for this port') def _receive(self, block=True): pass def pending(self): """Return how many messages are ready to be received. *Note*: This is kept around for backward compatibility. It's better to use iter_pending() to iterate over pending messages. This will read data from the device and put it in the parser. I will then return the number of messages available to be received. The value will not be reliable when receiving messages in multiple threads. If this is called on a closed port it will work as normal except it won't try to read from the device. """ with self._lock: if not self.closed: self._check_callback() self._receive(block=False) return len(self._messages) def iter_pending(self): """Iterate through pending messages.""" while True: message = self.poll() if message is None: return else: yield message def receive(self, block=True): """Return the next message. This will block until a message arrives. If you pass block=False it will not block and instead return None if there is no available message. If the port is closed and there are no pending messages IOError will be raised. If the port closes while waiting inside receive(), IOError will be raised. Todo: this seems a bit inconsistent. Should different errors be raised? What's most useful here? """ self._check_callback() # If there is a message pending, return it right away. with self._lock: if self._messages: return self._messages.popleft() if self.closed: if block: raise ValueError('receive() called on closed port') else: return None while True: with self._lock: # In the future we should allow self._receive() to # return a message. This would make the API more # consistent and also make it easier to implement # thread safe ports since self._messages is no longer # required. # # This can only be done if pending() is removed, since # it calls self._receive(). # # A commented out implementation is provided below. self._receive(block=block) # msg = self._receive(block=block) # if msg: # return msg # # (else check self._messages as before.) if self._messages: return self._messages.popleft() elif not block: return None elif self.closed: raise IOError('port closed during receive()') sleep() def poll(self): """Receive the next pending message or None This is the same as calling `receive(block=False)`.""" return self.receive(block=False) def __iter__(self): """Iterate through messages until the port closes.""" # This could have simply called receive() in a loop, but that # could result in a "port closed during receive()" error which # is hard to catch here. self._check_callback() while True: try: yield self.receive() except IOError: if self.closed: # The port closed before or inside receive(). # (This makes the assumption that this is the reason, # at the risk of masking other errors.) return else: raise class BaseOutput(BasePort): """ Base class for output port. Subclass and override _send() to create a new port type. (See portmidi.py for how to do this.) """ def __init__(self, name='', autoreset=False, **kwargs): """Create an output port name is the port name, as returned by output_names(). If name is not passed, the default output is used instead. """ BasePort.__init__(self, name, **kwargs) self.autoreset = autoreset def _send(self, message): pass def send(self, message): """Send a message on the port. A copy of the message will be sent, so you can safely modify the original message without any unexpected consequences. """ if not isinstance(message, Message): raise TypeError('argument to send() must be a Message') elif self.closed: raise ValueError('send() called on closed port') with self._lock: self._send(message.copy()) def reset(self): """Send "All Notes Off" and "Reset All Controllers" on all channels """ if self.closed: return ALL_NOTES_OFF = 123 RESET_ALL_CONTROLLERS = 121 for channel in range(16): for control in [ALL_NOTES_OFF, RESET_ALL_CONTROLLERS]: self.send(Message('control_change', channel=channel, control=control)) def panic(self): """Send "All Sounds Off" on all channels. This will mute all sounding notes regardless of envelopes. Useful when notes are hanging and nothing else helps. """ if self.closed: return ALL_SOUNDS_OFF = 120 for channel in range(16): self.send(Message('control_change', channel=channel, control=ALL_SOUNDS_OFF)) class BaseIOPort(BaseInput, BaseOutput): def __init__(self, name='', **kwargs): """Create an IO port. name is the port name, as returned by ioport_names(). """ BaseInput.__init__(self, name, **kwargs) BaseOutput.__init__(self, name, **kwargs) class IOPort(BaseIOPort): """Input / output port. This is a convenient wrapper around an input port and an output port which provides the functionality of both. Every method call is forwarded to the appropriate port. """ def __init__(self, input, output): self.input = input self.output = output # We use str() here in case name is None. self.name = '{} + {}'.format(str(input.name), str(output.name)) self._messages = self.input._messages self.closed = False self._lock = threading.RLock() def _close(self): self.input.close() self.output.close() def _send(self, message): self.output._send(message) def _receive(self, block=True): return self.input._receive() class EchoPort(BaseIOPort): def _send(self, message): self._messages.append(message) __iter__ = BaseIOPort.iter_pending class MultiPort(BaseIOPort): def __init__(self, ports, yield_ports=False): BaseIOPort.__init__(self, 'multi') self.ports = list(ports) self.yield_ports = yield_ports def _send(self, message): for port in self.ports: if not port.closed: # Todo: what if a SocketPort connection closes in-between here? port.send(message) def _receive(self, block=True): self._messages.extend(multi_receive(self.ports, yield_ports=self.yield_ports, block=False)) def multi_receive(ports, yield_ports=False, block=True): """Receive messages from multiple ports. Generates messages from ever input port. The ports are polled in random order for fairness, and all messages from each port are yielded before moving on to the next port. If yield_ports=True, (port, message) is yielded instead of just the message. If block=False only pending messages will be yielded. """ while True: # Make a shuffled copy of the port list. ports = list(ports) random.shuffle(ports) for port in ports: if not port.closed: for message in port.iter_pending(): if yield_ports: yield port, message else: yield message if block: sleep() else: break def multi_iter_pending(ports, yield_ports=False): """Iterate through all pending messages in ports. This is the same as calling multi_receive(ports, block=False). The function is kept around for backwards compatability. """ return multi_receive(ports, yield_ports=yield_ports, block=False) mido-1.1.18/mido/test_midifiles_load.py0000664000175000017500000000334313002711347020260 0ustar olembolemb00000000000000import io from pytest import raises from .messages import Message from .midifiles import MidiFile HEADER_ONE_TRACK = """ 4d 54 68 64 # MThd 00 00 00 06 # Chunk size 00 01 # Type 1 00 01 # 1 track 00 78 # 120 ticks per beat """ def parse_hexdump(hexdump): data = bytearray() for line in hexdump.splitlines(): data += bytearray.fromhex(line.split('#')[0]) return data def read_file(hexdump): return MidiFile(file=io.BytesIO(parse_hexdump(hexdump))) def test_no_tracks(): assert read_file(""" 4d 54 68 64 # MThd 00 00 00 06 # Chunk size 00 01 # Type 1 00 00 # 0 tracks 00 78 # 120 ticks per beat """).tracks == [] def test_single_message(): assert read_file(HEADER_ONE_TRACK + """ 4d 54 72 6b # MTrk 00 00 00 04 20 90 40 40 # note_on """).tracks[0] == [Message('note_on', note=64, velocity=64, time=32)] def test_two_tracks(): mid = read_file(""" 4d54 6864 0000 0006 0001 0002 0040 # Header 4d54 726b 0000 0008 00 90 40 10 40 80 40 10 # Track 0 4d54 726b 0000 0008 00 90 47 10 40 80 47 10 # Track 1 """) assert len(mid.tracks) == 2 # Todo: add some more tests here. def test_empty_file(): with raises(EOFError): read_file("") def test_eof_in_track(): with raises(EOFError): read_file(HEADER_ONE_TRACK + """ 4d 54 72 6b # MTrk 00 00 00 01 # Chunk size # Oops, no data here. """) def test_invalid_data_byte(): # Todo: should this raise IOError? with raises(IOError): read_file(HEADER_ONE_TRACK + """ 4d 54 72 6b # MTrk 00 00 00 04 # Chunk size 00 90 ff 40 # note_on note=255 velocity=64 """) mido-1.1.18/mido/test_syx.py0000664000175000017500000000204712775440355016155 0ustar olembolemb00000000000000from pytest import raises from .messages import Message from .syx import read_syx_file, write_syx_file def test_read(tmpdir): # p = tmpdir.mkdir("sub").join("hello.txt") path = tmpdir.join("test.syx").strpath message = Message('sysex', data=(1, 2, 3)) with open(path, 'wb') as outfile: outfile.write(message.bin()) assert read_syx_file(path) == [message] with open(path, 'wt') as outfile: outfile.write(message.hex()) assert read_syx_file(path) == [message] with open(path, 'wt') as outfile: outfile.write('NOT HEX') with raises(ValueError): read_syx_file(path) def test_write(tmpdir): # p = tmpdir.mkdir("sub").join("hello.txt") path = tmpdir.join("test.syx").strpath message = Message('sysex', data=(1, 2, 3)) write_syx_file(path, [message]) with open(path, 'rb') as infile: assert infile.read() == message.bin() write_syx_file(path, [message], plaintext=True) with open(path, 'rt') as infile: assert infile.read().strip() == message.hex() mido-1.1.18/mido/test_string_format.py0000664000175000017500000000522412775440355020210 0ustar olembolemb00000000000000import sys from pytest import raises from .messages import Message, parse_time from .messages import parse_string, format_as_string, parse_string_stream PY2 = (sys.version_info.major == 2) if PY2: from StringIO import StringIO else: from io import StringIO def test_parse_string(): assert (parse_string('note_on channel=2 note=3') == Message('note_on', channel=2, note=3)) assert (parse_string('sysex data=(1,2,3)') == Message('sysex', data=(1, 2, 3))) assert (parse_string('note_on time=0.5').time == Message('note_on', time=0.5).time) # nan and inf should be allowed assert parse_string('note_on time=inf').time == float('inf') assert str(parse_string('note_on time=nan').time) == 'nan' # Commas are not allowed with raises(ValueError): parse_string('note_on channel=2, note=3') with raises(ValueError): parse_string('++++S+S+SOIO(KOPKEPOKFWKF') with raises(ValueError): parse_string('note_on banana=2') with raises(ValueError): parse_string('sysex (1, 2, 3)') with raises(ValueError): parse_string('sysex (1 2 3)') def test_format_as_string(): assert (format_as_string(Message('note_on', channel=9)) == 'note_on channel=9 note=0 velocity=64 time=0') assert (format_as_string(Message('sysex', data=(1, 2, 3))) == 'sysex data=(1,2,3) time=0') assert (format_as_string(Message('sysex', data=())) == 'sysex data=() time=0') assert (format_as_string(Message('continue')) == 'continue time=0') def test_parse_string_stream(): # Correct input. stream = StringIO(""" note_on channel=1 # Ignore this # and this continue """) gen = parse_string_stream(stream) assert next(gen) == (Message('note_on', channel=1), None) assert next(gen) == (Message('continue'), None) # Invalid input. It should catch the ValueError # from parse_string() and return (None, 'Error message'). stream = StringIO('ijsoijfdsf\noiajoijfs') gen = parse_string_stream(stream) assert next(gen)[0] == None assert next(gen)[0] == None with raises(StopIteration): next(gen) def test_parse_string_time(): # These should work: parse_time('0') parse_time('12') parse_time('-9') parse_time('0.5') parse_time('10e10') parse_time('inf') parse_time('-inf') parse_time('nan') parse_time('2389284878375') # Will be a long in Python 2 # These should not with raises(ValueError): parse_time('banana') with raises(ValueError): parse_time('None') with raises(ValueError): parse_time('-') with raises(ValueError): parse_time('938938958398593L') mido-1.1.18/mido/test_ports.py0000664000175000017500000000470413002711347016465 0ustar olembolemb00000000000000from pytest import raises from .messages import Message from .ports import BaseIOPort def test_ioport(): class Port(BaseIOPort): def _open(self): self.close_called = False def _send(self, message): self._messages.append(message) def _close(self): self.close_called = True with Port('Name') as port: assert port.name == 'Name' assert not port.closed assert port._messages is port._parser.messages with raises(TypeError): port.send('not a message') with Port('Name') as port: message = Message('note_on') # Send and receive a message. (Blocking.) #port.send(message) #message2 = port.receive() #raise ValueError(('ost', message, message2)) # Receive a message. (Non-blocking.) port.send(message) message2 = port.poll() assert port.poll() is None with Port('Name') as port: message = Message('note_on') port.send(message) port.send(message) assert port.pending() == 2 assert list(port.iter_pending()) == [message, message] with Port('Name') as port: port.close() assert port.close_called port.close_called = False port.close() assert port.closed assert not port.close_called # Todo: should this type of port close (and/or stop iteration) # when there are no messages? # port.send(message) # port.send(message) # assert port.pending() == 2 # assert list(port) == [message, message] def test_close_inside_iteration(): # This type of port can close when it runs out of messages. # (And example of this is socket ports.) # # Iteration should then stop after all messages in the # internal queue have been received. message = Message('note_on') class Port(BaseIOPort): def __init__(self, messages): BaseIOPort.__init__(self) # Simulate some messages that arrived # earlier. self._messages.extend(messages) self.closed = False def _receive(self, block=True): # Oops, the other end hung up. if self._messages: return self._messages.popleft() else: self.close() return None message = Message('note_on') with Port([message, message]) as port: assert len(list(port)) == 2 mido-1.1.18/mido/test_midifiles.py0000664000175000017500000000141013002711347017252 0ustar olembolemb00000000000000import io from .messages import Message from .midifiles import tempo2bpm, bpm2tempo from .midifiles import MidiTrack, MetaMessage def test_tempo2bpm_bpm2tempo(): for bpm, tempo in [ (20, 3000000), (60, 1000000), (120, 500000), (240, 250000), ]: assert bpm == tempo2bpm(tempo) assert tempo == bpm2tempo(bpm) def test_track_slice(): track = MidiTrack() # Slice should return MidiTrack object. assert isinstance(track[::], MidiTrack) def test_track_name(): name1 = MetaMessage('track_name', name='name1') name2 = MetaMessage('track_name', name='name2') # The track should use the first name it finds. track = MidiTrack([name1, name2]) assert track.name == name1.name mido-1.1.18/mido/messages.py0000664000175000017500000004527413002711347016075 0ustar olembolemb00000000000000""" MIDI messages There is no need to use this module directly. All you need is available in the top level module. """ import sys PY2 = (sys.version_info.major == 2) # Pitchwheel is a 14 bit signed integer MIN_PITCHWHEEL = -8192 MAX_PITCHWHEEL = 8191 # Song pos is a 14 bit unsigned integer MIN_SONGPOS = 0 MAX_SONGPOS = 16383 class MessageSpec(object): """ Specifications for creating a message. status_byte is the first byte of the message. For channel messages, the channel (lower 4 bits) is clear. type is the type name of the message, for example 'sysex'. arguments is the attributes / keywords arguments specific to this message type. length is the length of this message in bytes. This value is not used for sysex messages, since they use an end byte instead. Table of MIDI messages: http://www.midi.org/techspecs/midimessages.php """ def __init__(self, status_byte, type_, arguments, length): """Create a new message specification.""" self.status_byte = status_byte self.type = type_ self.arguments = arguments self.length = length # Attributes that can be set on the object self.settable_attributes = set(self.arguments) | {'time'} def signature(self): """Return call signature for Message constructor for this type. The signature is returned as a string. """ parts = [] parts.append(repr(self.type)) for name in self.arguments: if name == 'data': parts.append('data=()') else: parts.append('{}=0'.format(name)) parts.append('time=0') sig = '({})'.format(', '.join(parts)) return sig def get_message_specs(): return [ # Channel messages MessageSpec(0x80, 'note_off', ('channel', 'note', 'velocity'), 3), MessageSpec(0x90, 'note_on', ('channel', 'note', 'velocity'), 3), MessageSpec(0xa0, 'polytouch', ('channel', 'note', 'value'), 3), MessageSpec(0xb0, 'control_change', ('channel', 'control', 'value'), 3), MessageSpec(0xc0, 'program_change', ('channel', 'program',), 2), MessageSpec(0xd0, 'aftertouch', ('channel', 'value',), 2), MessageSpec(0xe0, 'pitchwheel', ('channel', 'pitch',), 3), # System common messages MessageSpec(0xf0, 'sysex', ('data',), float('inf')), MessageSpec(0xf1, 'quarter_frame', ('frame_type', 'frame_value'), 2), MessageSpec(0xf2, 'songpos', ('pos',), 3), MessageSpec(0xf3, 'song_select', ('song',), 2), # 0xf4 is undefined. # 0xf5 is undefined. MessageSpec(0xf6, 'tune_request', (), 1), # 0xf7 is the stop byte for sysex messages, so should not be a message. # System real time messages MessageSpec(0xf8, 'clock', (), 1), # 0xf9 is undefined. MessageSpec(0xfa, 'start', (), 1), MessageSpec(0xfb, 'continue', (), 1), MessageSpec(0xfc, 'stop', (), 1), # 0xfd is undefined. MessageSpec(0xfe, 'active_sensing', (), 1), MessageSpec(0xff, 'reset', (), 1), ] def build_spec_lookup(message_specs): lookup = {} for spec in message_specs: status_byte = spec.status_byte if status_byte < 0xf0: # Channel message. # The upper 4 bits are message type, and # the lower 4 are MIDI channel. # We need lookup for all 16 MIDI channels. for channel in range(16): lookup[status_byte | channel] = spec else: lookup[status_byte] = spec lookup[spec.type] = spec return lookup def get_spec(type_or_status_byte): """Get message specification from status byte or message type name. For use in writing parsers. """ try: return Message._spec_lookup[type_or_status_byte] except KeyError: raise LookupError('unknown type or status byte') def check_time(time): """Check type and value of time. Raises TypeError if value is not an integer or a float """ if PY2 and isinstance(time, long): return if not (isinstance(time, int) or isinstance(time, float)): raise TypeError('time must be an integer or float') def check_channel(channel): """Check type and value of channel. Raises TypeError if the value is not an integer, and ValueError if it is outside range 0..15. """ if not isinstance(channel, int): raise TypeError('channel must be an integer') elif not 0 <= channel <= 15: raise ValueError('channel must be in range 0..15') def check_pos(pos): """Check type and value of song position. Raise TypeError if the value is not an integer, and ValueError if it is outside range MIN_SONGPOS..MAX_SONGPOS. """ if not isinstance(pos, int): raise TypeError('song pos must be and integer') elif not MIN_SONGPOS <= pos <= MAX_SONGPOS: raise ValueError('song pos must be in range {}..{}'.format( MIN_SONGPOS, MAX_SONGPOS)) def check_pitch(pitch): """Raise TypeError if the value is not an integer, and ValueError if it is outside range MIN_PITCHWHEEL..MAX_PITCHWHEEL. """ if not isinstance(pitch, int): raise TypeError('pichwheel value must be an integer') elif not MIN_PITCHWHEEL <= pitch <= MAX_PITCHWHEEL: raise ValueError('pitchwheel value must be in range {}..{}'.format( MIN_PITCHWHEEL, MAX_PITCHWHEEL)) def check_data(data_bytes): """Check type of data_byte and type and range of each data byte. Returns the data bytes as a SysexData object. Raises TypeError if value is not iterable. Raises TypeError if one of the bytes is not an integer. Raises ValueError if one of the bytes is out of range 0..127. """ # Make the sequence immutable. data_bytes = SysexData(data_bytes) for byte in data_bytes: check_databyte(byte) return data_bytes def check_frame_type(value): """Check type and value SMPTE quarter frame type. Raises TypeError if the value is not an integer. Raises ValueError if the value is out of range. """ if not isinstance(value, int): raise TypeError('frame_type must be an integer') elif not 0 <= value <= 7: raise ValueError('frame_type must be in range 0..7') def check_frame_value(value): """Check type and value of SMPTE quarter frame value. Raises TypeError if the value is not an integer. Raises ValueError if the value is out of range. """ if not isinstance(value, int): raise TypeError('frame_value must be an integer') elif not 0 <= value <= 15: raise ValueError('frame_value must be in range 0..15') def check_databyte(value): """Raise exception of byte has wrong type or is out of range Raises TypeError if the byte is not an integer, and ValueError if it is out of range. Data bytes are 7 bit, so the valid range is 0..127. """ if not isinstance(value, int): raise TypeError('data byte must be an integer') elif not 0 <= value <= 127: raise ValueError('data byte must be in range 0..127') def encode_channel(channel): """Convert channel into a list of bytes. Return an empty list of bytes, since channel is already masked into status byte. """ return [] def encode_data(data): """Encode sysex data as a list of bytes. A sysex end byte (0xf7) is appended. """ return list(data) + [0xf7] def encode_pitch(pitch): """Encode pitchwheel pitch as a list of bytes.""" pitch -= MIN_PITCHWHEEL return [pitch & 0x7f, pitch >> 7] def encode_pos(pos): """Encode song position as a list of bytes.""" return [pos & 0x7f, pos >> 7] class BaseMessage(object): """Base class for MIDI messages. Can be subclassed to create meta messages, for example. """ def copy(self, **overrides): """Return a copy of the message. Attributes will be overridden by the passed keyword arguments. Only message specific attributes can be overridden. The message type can not be changed. Example: a = Message('note_on') b = a.copy(velocity=32) """ # Make an exact copy of this object. klass = self.__class__ msg = klass.__new__(klass) vars(msg).update(vars(self)) for name, value in overrides.items(): try: # setattr() is responsible for checking the # name and type of the attribute. setattr(msg, name, value) except AttributeError as err: raise ValueError(*err.args) return msg def bytes(self): raise ValueError('bytes() is not implemented in this class') def bin(self): """Encode message and return as a bytearray. This can be used to write the message to a file. """ return bytearray(self.bytes()) def hex(self, sep=' '): """Encode message and return as a string of hex numbers, Each number is separated by the string sep. """ return sep.join('{:02X}'.format(byte) for byte in self.bytes()) def __eq__(self, other): """Compare message to another for equality.""" if not isinstance(other, BaseMessage): raise TypeError('comparison between message and another type') return vars(self) == vars(other) class SysexData(tuple): """Special kind of tuple accepts and converts any sequence in +=.""" def __iadd__(self, other): return SysexData(self + check_data(other)) class Message(BaseMessage): """ MIDI message class. """ # Quick lookup of specs by name or status_byte. _spec_lookup = build_spec_lookup(get_message_specs()) # This is needed for __init__() so it doesn't accept status bytes. _type_lookup = {name: value for name, value in _spec_lookup.items() \ if not isinstance(name, int)} def __init__(self, type, **arguments): """Create a new message. The first argument is typically the type of message to create, for example 'note_on'. """ try: spec = self._type_lookup[type] except KeyError: raise ValueError('invalid message type {!r}'.format(type)) vars(self)['type'] = type vars(self)['_spec'] = spec # Set default values. for name in spec.arguments: if name == 'velocity': vars(self)['velocity'] = 0x40 elif name == 'data': vars(self)['data'] = SysexData() else: vars(self)[name] = 0 vars(self)['time'] = 0 # Override defaults. for name, value in arguments.items(): try: setattr(self, name, value) except AttributeError as err: raise ValueError(*err.args) def __setattr__(self, name, value): if name in self._spec.settable_attributes: try: if name == 'data': value = check_data(value) else: globals()['check_{}'.format(name)](value) except KeyError: check_databyte(value) vars(self)[name] = value elif name in vars(self): raise AttributeError('{} attribute is read only'.format(name)) else: raise AttributeError( '{} message has no attribute {}'.format(self.type, name)) def __delattr__(self, name): raise AttributeError('attribute cannot be deleted') def bytes(self): """Encode message and return as a list of integers.""" status_byte = self._spec.status_byte if status_byte < 0xf0: # Add channel (lower 4 bits) to status byte. # Those bits in spec.status_byte are always 0. status_byte |= self.channel message_bytes = [status_byte] if self.type == 'quarter_frame': message_bytes.append(self.frame_type << 4 | self.frame_value) else: for name in self._spec.arguments: value = getattr(self, name) try: encode = globals()['encode_{}'.format(name)] message_bytes.extend(encode(value)) except KeyError: message_bytes.append(value) return message_bytes def __repr__(self): parts = [] for name in self._spec.arguments + ('time',): parts.append('{}={!r}'.format(name, getattr(self, name))) return ''.format(self.type, ' '.join(parts)) def __str__(self): return format_as_string(self) def __len__(self): if self.type == 'sysex': return len(self.data) + 2 else: return self._spec.length def build_message(spec, bytes, time=0): """Build message from bytes. This is used by Parser and MidiFile. bytes is a full list of bytes for the message including the status byte. For sysex messages, the end byte is not included. Examples: build_message(spec, [0x80, 20, 100]) build_message(spec, [0xf0, 1, 2, 3]) No type or value checking is done, so you need to do that before you call this function. (This includes time.) 0xf7 is not allowed as status byte. """ # This could be written in a more general way, but most messages # are note_on or note_off so doing it this way is faster. if spec.type in ['note_on', 'note_off']: attributes = { 'channel': bytes[0] & 0x0f, 'note': bytes[1], 'velocity': bytes[2], } elif spec.type == 'control_change': attributes = { 'channel': bytes[0] & 0x0f, 'control': bytes[1], 'value': bytes[2], } elif spec.status_byte < 0xf0: # Channel message. The most common type. if spec.type == 'pitchwheel': pitch = bytes[1] | ((bytes[2] << 7) + MIN_PITCHWHEEL) attributes = {'pitch': pitch} else: attributes = dict(zip(spec.arguments, bytes)) # Replace status_bytes sneakily with channel. attributes['channel'] = bytes[0] & 0x0f elif spec.type == 'sysex': attributes = {'data': tuple(bytes[1:])} elif spec.type == 'songpos': pos = bytes[1] | (bytes[2] << 7) attributes = {'pos': pos} elif spec.type == 'quarter_frame': attributes = {'frame_type': bytes[1] >> 4, 'frame_value' : bytes[1] & 15} else: attributes = dict(zip(spec.arguments, bytes[1:])) # Message.__new__() is used as an optimization to # get around argument checking. We already know that # the values are valid. msg = Message.__new__(Message) vars(msg).update(attributes) vars(msg).update({ 'type': spec.type, '_spec': spec, 'time': time, }) return msg def parse_time(text): if text.endswith('L'): raise ValueError('L is not allowed in time') if PY2: converters = [int, long, float] else: converters = [int, float] for convert in converters: try: return convert(text) except ValueError: pass raise ValueError('invalid format for time') def parse_string(text): """Parse a string of text and return a message. The string can span multiple lines, but must contain one full message. Raises ValueError if the string could not be parsed. """ words = text.split() type_name = words[0] arguments = words[1:] names_seen = set() kwargs = {} for argument in arguments: try: name, value = argument.split('=') except ValueError: raise ValueError('missing or extraneous equals sign') if name in names_seen: raise ValueError('argument passed more than once') names_seen.add(name) if name == 'data': if not value.startswith('(') and value.endswith(')'): raise ValueError('missing parentheses in data message') try: data_bytes = [int(byte) for byte in value[1:-1].split(',')] except ValueError: raise ValueError('unable to parse data bytes') kwargs['data'] = data_bytes elif name == 'time': try: time = parse_time(value) except ValueError: raise ValueError('invalid value for time') try: kwargs['time'] = time except AttributeError as err: raise ValueError(err.message) except TypeError as err: raise ValueError(err.message) else: try: kwargs[name] = int(value) except AttributeError as exception: raise ValueError(*exception.args) except ValueError: raise ValueError('{!r} is not an integer'.format(value)) return Message(type_name, **kwargs) def parse_string_stream(stream): """Parse a stram of messages and yield (message, error_message) stream can be any iterable that generates text strings, where each string is a string encoded message. If a string can be parsed, (message, None) is returned. If it can't be parsed (None, error_message) is returned. The error message containes the line number where the error occurred. """ line_number = 1 for line in stream: try: line = line.split('#')[0].strip() if line: yield parse_string(line), None except ValueError as exception: error_message = 'line {line_number}: {message}'.format( line_number=line_number, message=exception.args[0]) yield None, error_message line_number += 1 def format_as_string(message, include_time=True): """Format a message and return as a string. This is equivalent to str(message). To leave out the time attribute, pass include_time=False. """ if not isinstance(message, Message): raise ValueError('message must be a mido.Message object') words = [] words.append(message.type) names = message._spec.arguments if include_time: names += ('time',) for name in names: value = getattr(message, name) if name == 'data': value = '({})'.format(','.join(str(byte) for byte in value)) elif name == 'time': # Python 2 formats longs as '983989385L'. This is not allowed. value = str(value) value = value.replace('L', '') words.append('{}={}'.format(name, value)) return ' '.join(words) mido-1.1.18/mido/test_sockets.py0000664000175000017500000000112412775440355017000 0ustar olembolemb00000000000000from pytest import raises from .sockets import parse_address def test_parse_address(): assert parse_address(':8080') == ('', 8080) assert parse_address('localhost:8080') == ('localhost', 8080) with raises(ValueError): parse_address(':to_many_colons:8080') with raises(ValueError): parse_address('only_hostname') with raises(ValueError): parse_address('') with raises(ValueError): parse_address(':') with raises(ValueError): parse_address(':shoe') with raises(ValueError): parse_address(':0') with raises(ValueError): parse_address(':65536') # Out of range. mido-1.1.18/mido/parser.py0000664000175000017500000001051613002711347015551 0ustar olembolemb00000000000000""" MIDI Parser There is no need to use this module directly. All you need is available in the top level module. """ # # About running status: # # http://home.roadrunner.com/~jgglatt/tech/midispec/run.htm # http://stackoverflow.com/questions/3660964/get-note-data-from-midi-file # import sys from collections import deque from .messages import Message, build_message, get_spec PY2 = (sys.version_info.major == 2) class Parser(object): """ MIDI Parser Parses a stream of bytes and produces messages. Data can be put into the parser in the form of integers, byte arrays or byte strings. """ def __init__(self, data=None): """Create a new parser.""" self.messages = deque() self._reset() if data is not None: self.feed(data) def _reset(self): self._spec = None self._bytes = [] self._inside_sysex = False def _deliver(self, message=None): if not message: message = build_message(self._spec, self._bytes) self.messages.append(message) def _handle_status_byte(self, byte): try: spec = get_spec(byte) valid = True except LookupError: valid = False if self._inside_sysex and (0xf8 <= byte <= 0xff): # Realtime message inside sysex. # Deliver it straight away. if valid: message = build_message(spec, [byte]) self._deliver(message) elif byte == 0xf7: # End of sysex. if self._inside_sysex: self._deliver() self._reset() elif valid: # Start new message. self._spec = spec self._bytes = [byte] self._inside_sysex = (byte == 0xf0) else: # Ignore message. self._reset() def feed_byte(self, byte): """Feed one MIDI byte into the parser. The byte must be an integer in range 0..255. """ try: int(byte) except TypeError: raise TypeError('byte must be an integer') if not 0 <= byte <= 255: raise ValueError('byte must be in range 0..255') if byte >= 0x80: self._handle_status_byte(byte) else: # Data byte. self._bytes.append(byte) # If we have a complete messages, deliver it. if self._spec and len(self._bytes) == self._spec.length: self._deliver() self._reset() def feed(self, data): """Feed MIDI data to the parser. Accepts any object that produces a sequence of integers in range 0..255, such as: [0, 1, 2] (0, 1, 2) [for i in range(256)] (for i in range(256)] bytearray() b'' # Will be converted to integers in Python 2. """ if PY2 and isinstance(data, str): # Byte strings in Python 2 need extra attention. for char in data: self.feed_byte(ord(char)) else: for byte in data: self.feed_byte(byte) def pending(self): """Return the number of pending messages.""" return len(self.messages) def get_message(self): """Get the first parsed message. Returns None if there is no message yet. If you don't want to deal with None, you can use pending() to see how many messages you can get before you get None. """ if self.messages: return self.messages.popleft() else: return None def __iter__(self): """Yield messages that have been parsed so far.""" while len(self.messages): yield self.messages.popleft() def parse_all(data): """Parse MIDI data and return a list of all messages found. This is typically used to parse a little bit of data with a few messages in it. It's best to use a Parser object for larger amounts of data. Also, tt's often easier to use parse() if you know there is only one message in the data. """ return list(Parser(data)) def parse(data): """ Parse MIDI data and return the first message found. Data after the first message is ignored. Use parse_all() to parse more than one message. """ return Parser(data).get_message() mido-1.1.18/mido/__init__.py0000664000175000017500000000776513002711347016030 0ustar olembolemb00000000000000# -*- coding: utf-8 -*- """ MIDI Objects for Python Mido is a library for working with MIDI messages and ports. It's designed to be as straight forward and Pythonic as possible. Creating messages: Message(type, **parameters) -- create a new message MetaMessage(type, **parameters) -- create a new meta message Ports: open_input(name=None, virtual=False, callback=None) -- open an input port open_output(name=None, virtual=False, -- open an output port autoreset=False) open_ioport(name=None, virtual=False, -- open an I/O port (capable callback=None, autoreset=False) of both input and output) get_input_names() -- return a list of names of available input ports get_output_names() -- return a list of names of available output ports get_ioport_names() -- return a list of names of available I/O ports MIDI files: MidiFile(filename, **kwargs) -- open a MIDI file MidiTrack() -- a MIDI track bpm2tempo() -- convert beats per minute to MIDI file tempo tempo2bpm() -- convert MIDI file tempo to beats per minute merge_tracks(tracks) -- merge tracks into one track SYX files: read_syx_file(filename) -- read a SYX file write_syx_file(filename, messages, plaintext=False) -- write a SYX file Parsing MIDI streams: parse(bytes) -- parse a single message bytes (any iterable that generates integers in 0..127) parse_all(bytes) -- parse all messages bytes Parser -- MIDI parser class Parsing objects serialized with str(message): parse_string(string) -- parse a string containing a message parse_string_stream(iterable) -- parse strings from an iterable and generate messages Sub modules: ports -- useful tools for working with ports For more on MIDI, see: http://www.midi.org/ Getting started: >>> import mido >>> m = mido.Message('note_on', note=60, velocity=64) >>> m >>> m.type 'note_on' >>> m.channel = 6 >>> m.note = 19 >>> m.copy(velocity=120) >>> s = mido.Message('sysex', data=[byte for byte in range(5)]) >>> s.data (0, 1, 2, 3, 4) >>> s.hex() 'F0 00 01 02 03 04 F7' >>> len(s) 7 >>> default_input = mido.open_input() >>> default_input.name 'MPK mini MIDI 1' >>> output = mido.open_output('SD-20 Part A') >>> >>> for message in default_input: ... output.send(message) >>> get_input_names() ['MPK mini MIDI 1', 'SH-201'] """ from __future__ import absolute_import import os from .backends.backend import Backend from . import ports, sockets from .messages import Message from .messages import parse_string, parse_string_stream, format_as_string from .parser import Parser, parse, parse_all from .midifiles import MidiFile, MidiTrack, merge_tracks from .midifiles import MetaMessage, bpm2tempo, tempo2bpm from .syx import read_syx_file, write_syx_file __author__ = 'Ole Martin Bjorndalen' __email__ = 'ombdalen@gmail.com' __url__ = 'https://mido.readthedocs.io/' __license__ = 'MIT' __version__ = '1.1.18' # Prevent splat import. __all__ = [] def set_backend(name=None): """Set current backend. name can be a module name like 'mido.backends.rtmidi' or a Backend object. If no name is passed, the default backend will be used. This will replace all the open_*() and get_*_name() functions in top level mido module. The module will be loaded the first time one of those functions is called.""" glob = globals() if isinstance(name, Backend): backend = name else: backend = Backend(name, load=False, use_environ=True) glob['backend'] = backend for name in dir(backend): if name.split('_')[0] in ['open', 'get']: glob[name] = getattr(backend, name) set_backend() del os, absolute_import