# MIDIUSB: turning an Arduino board into a USB MIDI instrument

> MIDIUSB gives a board with native USB the ability to appear to a computer as a MIDI instrument, and everything it can do is bounded by the fact that it is built on PluggableUSB, which in turn limits it to specific boards and to a specific era of the Arduino IDE.

**arduino-libraries/MIDIUSB** — A MIDI library over USB, based on PluggableUSB

- Repository: https://github.com/arduino-libraries/MIDIUSB
- Stars: 576 · Forks: 98
- Language: C++
- License: LGPL-2.1
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/arduino-libraries-midiusb

## What the library actually does

MIDIUSB is an Arduino library for MIDI over USB, based on PluggableUSB, and the readme states its purpose in one sentence: it allows an Arduino board with USB capabilities to act as a MIDI instrument over USB.

That is a narrow, well defined job. The board enumerates as a class compliant MIDI device, so the operating system sees a MIDI port, and anything on the machine that speaks MIDI can send it notes and receive them back. No hardware MIDI port is required, and no serial MIDI stack is involved.

The library lives in the arduino-libraries organisation, which is the place where libraries are curated rather than maintained by their original authors, and the reference documentation is on the Arduino site under the library name. The licence is LGPL-2.1, and the code is C++.

The audience is a maker rather than a product team. The examples in the repository are the giveaway: a buzzer, a clock, a loop, and separate read and write programs. The buzzer plays a note through the board, the clock turns MIDI input into a display update, the loop echoes what it receives, and the read and write examples do one direction each. That is a set of teaching programs, and the library is small enough that reading it is a reasonable alternative to reading the documentation.

So the value proposition is not a MIDI stack with features you configure. It is a working, minimal example of how a microcontroller becomes a USB MIDI instrument, which is exactly what most people who search for this library are trying to build.

## The PluggableUSB constraint decides your board

The readme is explicit about compatibility, and the two sentences matter more than they look.

The library is based on PluggableUSB, so it is only compatible with Arduino IDE 1.6.6 and newer. And since PluggableUSB only targets boards with native USB capabilities, this library only supports those boards, with the examples given as Leonardo, Micro, Due, Zero and so on.

Both conditions are hard gates. The IDE version is a floor rather than a ceiling, so a current IDE is fine, and the readme does not describe an upper bound. The board requirement is the one that catches people, because the most common Arduino board does not have native USB. A classic Uno or Nano has a serial interface and a USB to serial converter, and that converter does not carry MIDI traffic, so the library simply does not apply to it.

There is a further consequence. Because the implementation sits on PluggableUSB rather than on the platform's own USB stack, the library inherits that framework's assumptions about the USB peripheral hardware on those boards. PluggableUSB is the same layer that other Arduino libraries such as the keyboard and mouse ones sit on, which is why those libraries share the same board list.

For an adopter, the check is quick. If the board you have in mind is on the list of native USB boards, the rest of the readme applies. If it is not, you are looking at a different approach entirely, and this library will not become compatible by upgrading the IDE.

## Five examples, and the metadata that ships with them

The examples directory holds five programs, and they are the fastest way to understand the API surface.

MIDIUSB_write sends notes, MIDIUSB_read receives them, MIDIUSB_loop echoes what arrives, MIDIUSB_buzzer plays a sound through the board, and MIDIUSB_clock drives a clock display from incoming MIDI data. Between them they cover the two directions, the echo case, an output case with a physical side effect, and an input case with a visual one.

That set is a good curriculum. A person learning USB MIDI on a microcontroller can flash the write program and see a note appear in a monitor, flash the read program and send a note into it, and work up to the clock, which is the one example that resembles a finished instrument.

Alongside the examples, the repository has the two files that every Arduino library needs and that many people forget. library.properties is the manifest the Arduino IDE reads to list the library in the library manager, and keywords.txt is the syntax highlighting keyword list. There is also a docs directory and a documentation directory, and a .codespellrc configuration, which is a reminder that the continuous integration includes a spell check.

The workflow badges tell you what runs on every change. There is a check-arduino workflow with the Arduino status badge, a compile-examples workflow, and a spell-check workflow, all three of which are shown at the top of the readme. Compiling every example on each push is a stronger guarantee than most small libraries offer, because it is the only way to know that a change has not broken a sketch for one of the supported boards.

## Testing on Linux with snd_seq_midi, fluidsynth and aconnect

The readme gives a complete Linux test procedure, which is unusual and worth following closely, because the order of the steps is what makes it work.

First you load the correct driver.

```bash
Load the correct driver (`sudo modprobe snd_seq_midi`)
```

Then you flash the board with the MIDIUSB_loop example and list the available ports with aseqdump.

```bash
Port    Client name                      Port name
  0:0    System                           Timer
  0:1    System                           Announce
 14:0    Midi Through                     Midi Through Port-0
 20:0    Arduino Micro                    Arduino Micro MIDI 1
```

Port 20 is the one the rest of the procedure uses, and it is the port your board appears as.

The next step starts a synthesizer, since a MIDI port on its own makes no sound.

```bash
fluidsynth --server --audio-driver=alsa -o audio.alsa.device=hw:0 ~/Synth.SF2
```

The soundbank path is the argument at the end, and the ALSA device is given as hw:0, which is the first hardware sound card on the machine.

Then, in another shell, you connect the board to the synth.

```bash
aconnect 20 128
```

And finally you play a file to the board.

```bash
aplaymidi  --port=20:0 ~/some_midi_file.mid
```

The readme explains that the file will be played after a complete roundtrip to the board, and that roundtrip is the point of the exercise. The loop example receives the note and sends it back, and the synth on the other end of the connection renders it. If nothing comes out, the failure is in one of the five links in that chain, and the procedure is arranged so you can check them one at a time.

## Where MIDIUSB is the wrong tool

Four limits, and the first two are about the hardware rather than the software.

The first is the board list, which was covered above but is worth repeating as a decision criterion. A classic Uno, a Nano, or any other board that reaches the computer over a USB to serial converter cannot use this library, and no amount of configuration will change that.

The second is the transport. This is USB class compliant MIDI and nothing else. There is no serial MIDI at 31250 baud, no DIN or mini DIN connector, and no 5 pin DIN breakout mentioned anywhere in the documentation. A project that needs to talk to an old hardware synth over a DIN cable needs a different library entirely, or an additional USB to MIDI interface next to the Arduino.

The third is the age of the published releases. Version 1.0.3 was published on 2017-08-05, and 1.0.4 and 1.0.5 were both published on 2023-08-11, minutes apart. The last push to the repository was on 2026-09-27, so the code is being touched, but the tagged versions that the Arduino library manager offers are from 2023.

The fourth is the shape of the library itself. There is no MIDI file parser, no virtual instrument framework, no clock, no arpeggiator and no message filtering beyond the examples. The readme does not describe a scheduling model, a note priority scheme or a handling policy for simultaneous note on events. For an instrument that has to behave musically, that work is yours.

None of these make the library bad. They make it a building block rather than a product, and the person who needs a building block is the person it suits.

## Licence, packaging and what the continuous integration checks

The licence is LGPL-2.1, with the licence text in LICENSE.txt at the root of the repository, and the library sits in the arduino-libraries organisation, which curates libraries that are no longer maintained by their original authors. This is not legal advice, and a company that ships the library inside a product should look at what LGPL means for redistribution in its own context.

The Arduino-specific packaging is the part that makes the library installable in the first place. The library.properties manifest is what the IDE reads, and the keywords.txt file is what drives the syntax highlighting for the example sketches. The examples live in their own directory with one folder per sketch, and the repository also carries a docs directory and a documentation directory.

The three workflows are the interesting part of the maintenance story. The check-arduino workflow reports the Arduino status, the compile-examples workflow compiles the examples, and the spell-check workflow runs a spell check, with a .codespellrc file at the root to configure it. Compiling every example on each change is the check that matters, because the library's supported surface is the set of boards it builds for, and a compile failure on one of them is a real regression.

The releases themselves are minimal, with 1.0.4 and 1.0.5 published on the same day, which is what a maintenance release of a stable library usually looks like. The repository is not archived, and the last push was on 2026-09-27, so the Arduino library manager version and the code in the repository are not necessarily the same thing.

## Conclusion

MIDIUSB is the right tool for a maker who wants a microcontroller to appear as a MIDI instrument to a laptop, for a clock driven by MIDI, or for a teaching setup where seeing the round trip through aseqdump and fluidsynth makes the protocol concrete. It is the wrong tool for a board without native USB, for anything that needs MIDI DIN or a 5 pin DIN port, and for a project that needs a maintained stream of fixes rather than a library whose last published version is from 2023. Before adopting, check that your board is one of the native USB models, confirm the example that matches your use compiles on the IDE version you have, and read the test procedure end to end before you buy a soundbank and a cable.

## FAQ

### What does the MIDIUSB Arduino library do?

It allows an Arduino board with USB capabilities to act as a MIDI instrument over USB, and it is based on PluggableUSB. The library is written in C++, is licensed under LGPL-2.1, and ships five example programs covering writing, reading, looping, a buzzer and a clock.

### Which Arduino boards work with MIDIUSB?

Only boards with native USB capabilities, because PluggableUSB only targets those boards. The readme gives Leonardo, Micro, Due and Zero as examples, and notes that the library is only compatible with Arduino IDE 1.6.6 and newer.

### How do I test MIDIUSB on Linux?

Load the driver with sudo modprobe snd_seq_midi, flash the MIDIUSB_loop example and list ports with aseqdump to find your board's port, start fluidsynth with a soundbank, connect the board to the synth with aconnect, and then play a file with aplaymidi using the port number.

### Does MIDIUSB support hardware MIDI ports?

The documentation describes USB class compliant MIDI only, with no mention of serial MIDI, DIN connectors or a breakout. A project that needs to talk to hardware over a DIN cable needs a different library or a separate USB to MIDI interface.

## Sources

- [arduino-libraries/MIDIUSB on GitHub](https://github.com/arduino-libraries/MIDIUSB)
- [Issues](https://github.com/arduino-libraries/MIDIUSB/issues)
- [License: LGPL-2.1](https://github.com/arduino-libraries/MIDIUSB/blob/master/LICENSE)
- [README](https://github.com/arduino-libraries/MIDIUSB/blob/master/README.md)
- [Releases](https://github.com/arduino-libraries/MIDIUSB/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/arduino-libraries-midiusb