Midiex overview

Midiex is a cross-platform, real-time MIDI processing library in Elixir.

midir Rust library

Using Rustler, Midiex wraps the excellent midir Rust library.

Midir support a range of platforms and backends, such as:

• ALSA (Linux)
• WinMM (Windows)
• CoreMIDI (MacOS, iOS)
• WinRT (Windows 8+),
• Jack (Linux, macOS)

Using WinRT or Jack requires special feature flags enabled. See the midir GitHub and create docs for more details.

The hot-plug support of MIDI devices on MacOS is made possible with with the Rust coremidi library.

Status

This library is currently under active development and it’s API is likely to change. It's been tested on MacOS only although it is currently building on Mac (M-series and x86), Linux (64-bit ARM, RISC-V and x86) and Windows (x86_64) with precompiled binary packages available (see the Getting started section below).

API

At it's most basic level, the core functions of Midiex are for:

• listing or counting MIDI ports availble (for example, a keyboard or synth)
• opening or closing connections to MIDI ports
• sending or receiving messages to and from connections
• creating virtual output connections so your Elixir application appears as a MIDI input port on the host OS.
• creating virtual input connections so your Elixir application appears as a MIDI output port on the host OS.

Feature support

Not all midir features have been wrapped and some features are backend specific:

• Virtual output connection: currently on every platform but Windows
• Virtual input connection: currently on every platform but Windows
• Notification messages and hot-plug support: currently implemented on MacOS (e.g. to receive notifications when a device has been plugged in or removed).

MIDI messages

MIDI messages are in binary format. They're usually in the format of one status byte followed by one or two data bytes.

For example, the status byte for 'Note On' is 0x90 in HEX format. The data byte representing the note Middle C is 60. The data byte representing velocity (i.e. how hard the key was struck when the note was played) is an integer in the range 0 - 127 where 127 is the loudest.

Putting that together, the message to play Middle C at a velocity of 127 is: <<0x90, 60, 127>> You can stop the same note from playing by sending the 'Note Off' status byte 0x80, which would make the message: <<0x80, 60, 127>>.

For more information on MIDI messages, see the offical MIDI Assocations Specifications, Expanded MIDI 1.0 message list or the various articles online such as this one.

Example

# List MIDI ports
Midiex.ports()

# Create a virtual output connection
piano = Midiex.create_virtual_output("piano")

# Returns an output connection:
# %Midiex.OutConn{
#   conn_ref: #Reference<0.1633267383.3718381569.210768>,
#   name: "piano",
#   port_num: 0
# }

# Send to MIDI messages to a connection
note_on = <<0x90, 60, 127>>
note_off = <<0x80, 60, 127>>

Midiex.send_msg(piano, note_on)
:timer.sleep(3000) # wait three seconds
Midiex.send_msg(piano, note_off)

Getting started

Platforms with precompiled binaries

Since v0.6, Midiex uses Rustler Precompiled to provide precompiled binaries on the following platforms:

• Apple Mac:
  • M-series: aarch64-apple-darwin
  • x86-series: x86_64-apple-darwin
• Linux x86 based:
  • x86_64-unknown-linux-gnu
  • x86_64-unknown-linux-musl
• Linux ARM based:
  • aarch64-unknown-linux-gnu
  • aarch64-unknown-linux-musl
• Linux RISC-V based:
  • riscv64gc-unknown-linux-gnu
• Windows x86 based:
  • x86_64-pc-windows-msvc
  • x86_64-pc-windows-gnu

This means you shouldn't need the Rust build tools for the above plaforms. Just add midiex as a dependency to your Elixir project and Rustler will download and install the correct binary.

Rust build tools

If you want to use Midiex on a different platform than those listed above, or want to force complication, you'll need to have Rust's build tools installed. See BUILDING.md for more information.

Adding it to your Elixir project

The package can be installed by adding midiex to your list of dependencies in mix.exs:

def deps do
  [
    {:midiex, "~> 0.6.3"}
  ]
End

Using within LiveBook and IEx

Mix.install([{:midiex, "~> 0.6.3"}])

LiveBook tour

Also see the introductory tour in LiveBook at /livebook/midiex_notebook.livemd.

Documentation

The docs can be found at https://hexdocs.pm/midiex.