Apple MIDI 2.0 Driver and API NAMM 2024
Torrey Walker from Apple will give an in depth look at the new Apple updates for MIDI.
Join us on YouTube for Torrey Walker’s presentation at Winter NAMM 2024.
Torrey Walker from Apple will give an in depth look at the new Apple updates for MIDI.
Join us on YouTube for Torrey Walker’s presentation at Winter NAMM 2024.
The Wind Synthesizer R1 is a new form of wind instrument created by Robkoo.
With its intuitive design, audio technology, and realistic sounds, R1 makes performing music easier than ever.
USB MIDI 2.0 was released by the USB-IF in June 2020, with Apple adding support within CoreMIDI in October 2021 and Google added support in Android in August 2022. At the time of writing, Microsoft has announced upcoming support for MIDI 2.0 and now on a public Github, and also patches have been submitted by ALSA for inclusion in Linux Kernel 6.5. An update to the MIDI 2.0 UMP specification was approved in the first half of 2023.
For a more complete timeline see https://www.midi.org/midi-articles/detailed-timeline-of-midi-2-0-developments-since-january-2020
This technical guide to building a USB MIDI 2.0 device is the first in a series of articles targeted specifically to device developers.
For musicians, please see this article: https://www.midi.org/midi-articles/what-musicians-and-artists-need-to-know-about-midi-2-0
This series (based on the work of the OS API Working Group of the MIDI Association) focuses on configuring the USB descriptors to provide the best experience for your users. It shows you how to handle Group Terminal Blocks and Function Blocks, Multiple UMP Endpoints and compatibility with USB Hosts that can only handle USB MIDI 1.0, as well MIDI 1.0 Applications.
This guide assumes that the reader is familiar with the following specifications:
In MIDI 1.0 most Devices present an IN port and an OUT port and that is all that is required.
In MIDI 2.0 there are several factors to consider:
Design of a simple Desktop Monosynth
Let’s imagine we have a simple single channel desktop monosynth. We want to use MIDI 2.0 Protocol where we can because the parameters (e.g. filter cutoff frequency) benefit from having more than 128 steps. While the MIDI 2.0 Protocol boasts a massive improvement in resolution and capabilities and allows us to future-proof the product, we also need to have MIDI 1.0 compatibility for both older OS’s and MIDI 1.0 Applications.
First, we start gathering the details of the synth. These values will be repeated into several different fields. They have been color-coded so you can easily refer to the source of information.
Detail | Value | String Rules |
Manufacturer Name | “ACME Enterprises” | UTF16, Max Length: 254 bytes |
Product Name | “ACMESynth” | UTF-8, Max Length: 98 bytes |
Product Instance Id | “ABCD12345”
The Product Instance Id of a device is any |
ASCII, Max Length: 42 bytes
don’t include characters that are: Less than or equal to 0x20 Greater than 0x7F Equal to 0x2C (‘,’) |
Protocol | MIDI 2.0 Protocol (with a fallback to MIDI 1.0 Protocol) | |
Function 1 | ||
Function 1 Name | “Monosynth” | UTF-8, Max Length: 98 bytes |
Function 1 Channels Needed | 1 Channel at a time used bidirectionally |
The string values in this table will be used in USB descriptors, UMP messages, and MIDI-CI messages. Each of these systems have limitations that should be adhered to. The table above provides a set of rules that best suits all strings used in a new device.
It is recommended that Product Instance Id is used as the USB iSerial value. For compatibility with Windows it is suggested iSerial numbers don’t contain characters that are:
In USB MIDI 1.0, devices can present a USB IN Data Endpoint and/or a USB OUT Data Endpoint with up to 16 virtual MIDI cables each. Note that USB IN and USB OUT refer to data direction from the point of view of the USB Host. Each virtual MIDI cable can be considered equivalent to a MIDI DIN jack with streaming MIDI 1.0 for up to 16 channels each. In USB MIDI 2.0, the device can present a single USB IN Data Endpoint and/or a single USB OUT Data Endpoint that represents a single Universal MIDI Packet (UMP) data stream. It is strongly recommended that an IN/OUT Data Endpoint pair is presented to create a bi-directional UMP Endpoint to fully take advantage of MIDI 2.0.
At this point we start building the USB Descriptors. Developers should ensure that the following fields are filled out with the information above.
When defining the USB descriptors we can see that this Device only needs to set-up a single Interface.
Note some USB details in this document use an id reference for a separate string descriptor. The strings are shown for brevity. If the value is omitted, the id should be set to 0, not to an entry with a blank string.
Detail | Product Detail Value | Id of String Descriptor Referenced Value |
iManufacturer | Manufacturer Name | “ACME Enterprises” |
iProduct | Product Name | “ACMESynth” |
iSerialNumber | Product Instance Id | “ABCD12345” |
iInterface | Model Name* | “ACMESynth” |
*More complicated setups with multiple interfaces (and multiple UMP endpoints) will be discussed in a followup article. For a simple Device the iInterface and the iProduct can be the same.
A USB MIDI 2.0 Device should include a set of USB MIDI 1.0 Class Descriptors so that when it is plugged into a Host which does not understand MIDI 2.0, it can operate as a MIDI 1.0 Device.
When declaring MIDI 1.0 Class Specific Descriptors, you should provide a text string name for all Embedded MIDI Jacks.
Detail | Product Detail Value | Id of String Descriptor Referenced Value |
iJack | Function 1 Name | “Monosynth” |
Most Host MIDI 1.0 Class drivers do not collect information about the topology inside the MIDI Function, such as External MIDI Jacks or Elements.
For the best compatibility on OS’s, each UMP Endpoint is represented by a single Interface. The Interface has an In and an Out USB Endpoint that represents a bidirectional UMP Endpoint.
Devices expose their functions and topology using Function Blocks regardless of transport. USB MIDI 2.0 has the additional requirement of Group Terminal Blocks which are declared in the Device descriptors and designed in consideration of the device’s Function Blocks.
Each USB Endpoint declares the Group Terminal Block Id’s used. The USB Device has a list of Group Terminal Block descriptors that match these Id’s.
In our example, the Monosynth function only uses one channel, so we only need to declare the use of one UMP Group. While there are different ways of declaring Group Terminal Blocks we will look at just one way first and revisit with different configurations with the pros and cons of each at another time.
Option 1: Declare a Single Group Terminal Block on Group 1 with a length of 1 Group
For simple Devices like our Monosynth that only connect over USB this may be the most straightforward way of connecting to a computer and provides the best backwards compatibility to MIDI 1.0 Applications.
The Group Terminal Block should have the following settings:
Detail | Value | String Rules |
bGrpTrmBlkID | Block Id | 1 |
bGrpTrmBlkType | Block Type | 0x00 – bidirectional |
nGroupTrm | Starting Group | 0x00 – Group 1 |
nNumGroupTrm | Number of Groups Spanned | 1 |
iBlockItem | Function 1 Name | Id of String Descriptor Referenced Value – “Monosynth” |
bMIDIProtocol | Block Protocol* | 0x11 (MIDI 2.0 Protocol) |
USB Endpoints under the Interface should have the following values:
Detail | Value | String Rules |
bNumGrpTrmBlock | Number of GTB’s | 1 |
baAssoGrpTrmBlkID | Block Id | 1 |
With the descriptors now defined, let’s observe the interaction with an OS that supports MIDI 2.0.
While MIDI 2.0 Protocol is declared in the Monosynth Group Terminal Block, a host Application may send MIDI 1.0 Channel Voice Message either intentionally or accidentally. In UMP 1.1 Stream Configuration messages may also be used to switch Protocols. To ensure the best compatibility with incoming messages a MIDI 2.0 Device supporting MIDI 2.0 Protocol should also handle and process MIDI 1.0 Channel Voice messages. We will discuss handling this in a follow up article.
MIDI 2.0 applications should, where possible, connect to the connection labelled “MIDI 2.0” (as seen below). MIDI 1.0 applications are generally only able to connect to the “Monosynth” connection and talk using MIDI 1.0 Protocol. The OS converts these MIDI 1.0 byte stream messages to UMP format between the Device and the application.
Note: OSX has supported USB MIDI 2.0 since OSX 11. Prior to OSX 14 (developer release) only the “Monosynth” entity is shown.
Android 13+ currently connects to the USB MIDI Interface and can use either the USB MIDI 1.0 function on Alternate Setting #0 or use the USB MIDI 2.0 function on Alternate Setting #1 on a per application basis. When apps call midiManager.getDevicesForTransport( MidiManager.TRANSPORT_UNIVERSAL_MIDI_PACKETS), they see the USB MIDI 2.0 device as a MIDI 2.0 device. If they call midiManager.getDevicesForTransport( MidiManager.TRANSPORT_MIDI_BYTE_STREAM), they see the device as a MIDI 1.0 device. A device can be opened as only one of the two modes at once.
See https://developer.android.com/reference/android/media/midi/package-summary for more information. https://github.com/android/midi-samples contains some sample applications developers can test with.
In OS’s that don’t yet support MIDI 2.0, the USB MIDI 1.0 function may be loaded to expose MIDI 1.0 Ports as declared in the MIDI 1.0 Class Specific Descriptors (on Alternate Setting 0). Currently in Windows this looks like:
While in current versions of Linux this looks like:
These USB settings form the beginnings of a USB MIDI 2.0 Device.
In the next part of this series we look at recommended UMP Endpoint messages and how Function Blocks interact with Group Terminal Blocks to extend the usability of MIDI 2.0. We will look at other options for having more functions in your Device and how best to support them.
As computers have become central components in many MIDI systems, USB has become the most widely used protocol for transporting MIDI data. With the introduction of MIDI 2.0, the USB Implementers Forum’s USB MIDI 2.0 working group, headed by members of the MIDI Manufacturers Association (MMA) and the Association of Musical Electronics Industry (AMEI), have updated the USB Class Definition for MIDI Devices. This spec defines how USB transports MIDI data.
The key to the updated spec is use of the new Universal MIDI Packet to support MIDI 2.0’s new functionality, while retaining backward compatibility with MIDI 1.0.
Highlights of operation over USB include:
·Better support for deterministic, high-speed throughput (up to hundreds of times MIDI’s original speed)
·Old and new devices work with any operating system that supports the updated USB Class Definition for MIDI Devices
·As with the previous version, no drivers needed for compliant devices
·Supports up to 256 MIDI Channels in 16 Groups of the new Universal MIDI Packet
·Can provide more accurate timing for dense MIDI streams
·Devices can run multiple Endpoints to use more than 256 Channels
·Over time, simpler to implement than USB MIDI 1.0
·Enhances the use of MIDI 2.0 mechanisms including MIDI Capability Inquiry (MIDI-CI)
·Supports both MIDI 1.0 Protocol and MIDI 2.0 Protocol Data
·Devices can declare UMP Group IN/Out pairs for use by MIDI-CI
·Devices can declare that more than one UMP Group is used for a shared or related function.
·Added Bandwidth descriptors for more predictable use of higher speeds.
·Added support for Interrupt transactions as well as Bulk (USB MIDI 1.0 uses Bulk only) for more deterministic control over jitter and throughput.
According to Mike Kent of the USB-IF Audio Working Group and MMA Technical Standards Board, “The new spec provides operating system manufacturers, like Apple, Microsoft, Google, Linux, and others, a clearly defined path for moving forward with MIDI 2.0.”
As with MIDI itself, the new USB Class Definition has been a collaborative effort, involving multiple companies from around the world. In conjunction with its members, the MMA and AMEI will continue enhancing the MIDI 2.0 specification, and assist manufacturers with incorporating MIDI 2.0’s features into the next generation of music gear.
Details on the USB Class Definition for MIDI Devices specification are available from the link below.
We encourage all MIDI developers to download the specification and we will adding articles to MIDI.org with more details on the USB-MIDI 2.0 specification soon.
In 2015 Android introduced MIDI support. Android has billions of users which means there’s a whole lot of people with MIDI compatible devices in their pocket!
In this article I’ll explore the most popular types of MIDI applications on Android and how to choose the right MIDI API when developing your own app.
The two most popular types of MIDI app are:
1) Apps controlled by MIDI. These are apps which primarily receive MIDI data, such as synthesizers, drum machines and DJing apps.
2) MIDI controller apps. These apps are used to control other apps, external hardware or external software (such as a desktop audio workstation).
The virtual analog synthesizer app, DRC can be played using an external MIDI keyboard
These types of apps are designed to control other apps by sending MIDI to them. Examples include:
Super MIDI Box is a MIDI drum machine and step sequencer
A little-known feature of Android is that when connected to a USB host (like a computer) it can become a class compliant USB-MIDI device. This is done in the USB settings.
Once the USB mode is changed to MIDI, it will appear on the host as a MIDI device with one input channel and one output channel. A MIDI controller app can then be used to control software, such as a Digital Audio Workstation (DAW), on the host.
Inside the app the MIDI device will show up as “Android USB Peripheral” with a single input port and a single output port.
DRC app connected to the Android USB Peripheral MIDI device
In order to develop a MIDI application on Android you’ll need to use one or both of the available MIDI APIs. Here’s a summary of the available APIs and their features:
In Android Marshmallow (API 23) the JVM Midi API was released. It can be accessed using Kotlin or the Java Programming Language. It enables you to enumerate, connect and communicate with MIDI devices over USB, Bluetooth LE and other apps advertising as virtual MIDI services.
Pros
Cons
You must use this API for enumerating and connecting to MIDI devices, however, for reading and writing you can choose between this API and the Native Midi API described below.
In Android Q the Native MIDI API was released. It’s specifically designed for communicating with MIDI devices inside an audio callback which makes it easy to control audio rendering objects, for example a software synthesizer.
This API only handles sending and receiving MIDI data, not MIDI device enumeration or connection. That still needs to be done using the JVM API.
Pros
Cons
You can start developing a MIDI app using Android Studio. You’ll want to check out the following resources:
You should also take a look at the existing MIDI apps on the Google Play Store.
If you are using audio in your app you might want to check out the Oboe library for developing high performance audio apps.
If you have questions about developing MIDI apps on Android feel free to ask them on the android-midi group. Good luck and have fun!
The Tirare is a custom performance interface. In Italian, Tirare means: (to) throw, (to) to pull. The name refers to the primary performative action employed in order to generate sound. Initially, I was trying to create a form of MIDI concertina. I wanted to pull and push the interface to generate sound, similar to a concertina. I also made the intentional choice to not use a myriad of interface sensors like buttons, switches, sliders, etc. My goal was to create a simple interface that could handle all operations without the need for excessive methods of control.
I decided to use a Gametrak as the primary hardware for this interface (https://en.wikipedia.org/wiki/Gametrak). I have used the Gametrak in previous performances as a controller. This time I set out to assimilate the pieces of the Gametrak into a new interface. I used only one of the joysticks in my final design.
The Gametrak is a video game controller created by In2Games. The Gametrak controller consists of two three-dimensional (3D) joysticks. Each joystick generates X, Y, and Z data (when the string is pulled out of the interface), so each joystick control works like three faders that are interdependent of one another. Each joystick can be manipulated on its X, Y, and Z axes. Each axis outputs an integer. The uniqueness of the Gametrak lies in the three-dimensional joystick. The handle on both 3D faders is connected to a string-pot that pulls out of the box. A string-pot is simply a potentiometer that is turned by pulling a long, spring-wound spool of string. This pulling of the string-pot turns the potentiometer which outputs data. According to In2Games, the mechanisms can determine position, “to an accuracy of 1 millimeter anywhere within a 3 meter cube around the unit, with no processor overhead or time delay.” This level of responsiveness and precision was essential for the controller’s original purpose — to control a virtual golf swing! This level of precision and responsiveness is also well suited for use as a real-time performance interface.
I disconnected the main logic board in the Gametrak and connected one of the joysticks directly to the analog inputs on an Arduino Pro Micro. Since the Arduino’s ADC is 10-bit, the values genrated by the joysticks range from 0-1023. I scaled these values in the Arduino software to a range of 0-127 to conform to MIDI 1.0. Each axis of the joystick outputs two MIDI CC values. I programmed this feature to allow the Tirare to function with MPE software.
The next step was to reassemble the pieces into a new form. I looked for an old concertina thinking I could insert the Gametrak pieces but this search was unsuccessful. After several attempts to create my own bellow for the Tirare, I realized copying the physical form of a concertina would not work because there would be no way to keep the bellow from resting on the string. I decided to find a new physical form to house the Gametrak pieces. Ultimately, I chose to use two small round pieces of wood (craft store), basic drawer handles (Home Depot), and a small strainer (dollar store). I initially intended this design to be a working prototype and not the final product. However, I have yet to find a better way to embody the joystick.
I used the flywheel from the unused joystick to reroute the string from the potentiometer. This was necessary because I wanted the joystick as close to the center of the piece of wood as possible. However, the size and shape of the wood and the parts left me few options for assembly. It was important to route the string from the bottom of the joystick becue the IC board on the joystick prevented any other way of routing the string.
Data is generated when the joystick is moved or the string is pulled. The Arduino scales the incoming data and generates MIDI CC values. The Arduino sends MIDI data over USB to MaxMSP. I use MaxMSP to receive the MIDI data from the Tirare and route that data to Kyma to generate sound.
The string-pot also generates MIDI CC values during performance. I use MaxMSP to detect the direction the string is moving at any time, and I map that data to different destinations. I basically get two unique data streams from a single movement. In MaxMSP, I set thresholds at various points along the movement of the string in order to generate events that are used to trigger notes (see photo below), CC values, and control messages for Kyma.
My software is very simple. I use the view on the left (below) to initialize the Tirare and turn on the three axes. I use the view on the right (below) during performance to monitor the values from each axis and to monitor where the string values are in relation to the triggers I set up for controlling notes, expression, and control for Kyma.
The Tirare is only a controller and does not generate sound. The combination of physical interface, software mapping layer, and sound production software make up the entire Data-driven Instrument for live performance.
The next step for this projects is to allow for MIDI over USB or Bluetooth. I am currently working on a Max patch that will allow the Tirare, when connected, to change the way it transmits MIDI — USB or BLE. I also still have hope that I will dream up a better physical form for the Tirare.
***Video Coming Soon!
MIDI has stayed relevant for over 30 years by adapting to the different ways that computers send information to and from external devices. MIDI can now be sent over 5 Pin DIN, Serial Ports, USB, Firewire, Ethernet, Bluetooth and more. But currently the most prevalent way to connect to computers, tablets and smartphones is USB. This article will cover the basics of USB-MIDI.
In the early 1990’s, there were far too many types of connectors on computers. There were separate serial ports, parallel ports, keyboard and mouse connections, and joystick ports, It was hard for people to tell whether the peripheral they were buying would actually work with their computer. So Compaq, Intel, Microsoft and NEC ( joined later by Hewlett-Packard, Lucent and Philips) formed the USB Implementers Forum, Inc, a non-profit corporation to publish the specifications and organise further development in USB. Similar to the MIDI Manufacturers Association, the USB-IF makes sure that there is interoperability between USB devices.
The USB-IF had some clear goals when first developing the USB specification
The basic USB system architecture is actually pretty simple and consists of the following main components:
The Universal Serial Bus is a host controlled bus. All data transfers are initiated and controlled by the host and USB peripherals are slaves responding to host commands. So for USB MIDI peripheral devices you need a computer, smartphone or tablet in the system to control and initiate USB communication.
USB devices are defined into specific functional classes, for example image, human interface devices (keyboard, mouse, joystick), mass storage, and audio. The operating system can then know what the devices is designed to do and automatically load what is called a class compliant driver for that type of devices. In 1999, the MIDI specification was developed by the USB-IF in cooperation with the MIDI Manufacturers Association and included in the Audio class of devices. That is why sometimes when you connect a USB-MIDI peripheral, the OS will display a message that says USB-Audio devices connected. As far as USB is concerned MIDI is an Audio Class Compliant device.
Class compliant drivers are convenient because you don’t have to download any external software. But often manufacturer specific drivers provide added functionality. Let’s use Yamaha has an example. Because data transfer on USb is much faster than 5 pin DIN it is possible to have multiple ports of MIDI (a port is a group of 16 MIDI channels) on a single USB cable. The dedicated Yamaha USB Driver provides for 8 ports of high speed USB, includes the names of all the devices that are compatible with the driver and has some routing capabilities. These features are only available if you download the driver from Yamaha’s website. Also many audio interfaces are also MIDI interfaces and audio and MIDI travel over the USb cable. So if you purchase a MIDI or Audio interface you should always check the product manual and manufacturer’s website to see if there is a dedicated USB driver for your product that provides added functionality. Often even if the manufacturer specific driver is available when connected to a device which don’t allow driver downloads into the operating system (for example iOS devices), the product will still work as a class compliant USB device.
Over the years, USB has developed and there are now a number of different cable types and USB specifications. Let’s take a look at the different connectors.
Originally most desktop and laptops computers had the standard sized Type A USB connector. A standard USB cable has a Type A connector on one end to connect to the host and a Type B connector on the other end to connect to the peripheral device. This is still the most common cable to connect a MIDI instrument to a computer.
The Type A connector has a pin that supplies power to external peripherals so you need to be carefully about trying to connect two hosts via a Type A to Type A cable. This can cause serious damage to your gear so consult the manufacturer and manual before attempting this.
The Type A connector is for host controllers (computers, smartphones, tablets and some digital musical instruments that act as hosts) and USB hubs. A USB hub is a device that expands a single (USB) port into several so that there are more ports available to connect devices to a host system.USB hubs are often built into equipment such as computers, computer keyboards, monitors, or printers. When a device has many USB ports, they all usually stem from one or two internal USB hubs rather than each port having independent USB circuitry. If you need more USB ports, there are also external hubs that you can buy. You need to check to see if your USB peripherals need to be powered by USB and if they do you may need a powered USB hub.
On many digital musical instruments you find two USB connectors – one Type A connector labeled To Device and one Type B labeled To Host . The To Host is usually used to send MIDI, Audio or both Audio and MIDI to a computer, smartphone or tablet. If your digital music product sends both MIDI and Audio over USB, you will almost certainly need a manufacturer specific driver.
The To Device is usually used for USB Storage devices like Flash Thumb drives, but it can be used for other things depending on what the Host music product supports for device classes.
Considered the standard and most common type of connector, A-style connectors are found on the PC or charger side of most cables. This flat, rectangular interface is held in place through friction. Durable enough for continuous connection but easy enough for users to connect and disconnect, this connector type is also available in micro variations.
Type-B USBs were traditionally used with printer cables but, they’re now found on many popular models of Android™ smartphones and external hard drives. These USBs feature a square interface and are available as a Micro-USB B, USB Mini-b (5-pin), and USB Mini-b (4-pin).
The newest type of connector on the market, Type-C is a one-size-fits-all solution. Developed to support devices with a smaller, thinner and lighter form factor. Type-C is slim enough for a smartphone or tablet, yet robust enough for a desktop computer. It also has the advantage of a reversible plug orientation and cable direction, eliminating the guesswork about which direction the connection goes.
USB Type-C is designed as a one-size-fits-all solution for data transfer and power supply on any device. Featuring a smaller connector, Type-C fits into one multi-use port to simultaneously charge devices and transfer data and also offers backward compatibility to support previous USB standards (2.0, 3.0, and 3.1).
Type-C is quickly becoming the new standard for operating systems and hardware providers; Intel’s Thunderbolt recently switched to USB Type-C ports while enabling cross compatibility with USB 3.1. The new Apple MacBooks feature a Type-C port.
The USB-IF predicts that by 2019, all laptops, tablets, mobile phones, and other consumer electronics will be equipped with USB Type-C.
In the meantime, if you have a newer computer, you may need an adapter to connect your MIDI gear to your computer.