View Source README

Midiex

Documentation Package

Midiex overview

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

midir-rust-library

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.

status

Status

This library is currently under active development and it’s API is likely to change. It's been tested on MacOS only.

api

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 a virtual output connection so your Elixir application appears as a MIDI input port on the host OS.
  • creating a virtual input connection so your Elixir application appears as a MIDI output port on the host OS.

feature-support

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.

midi-messages

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

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

Getting started

adding-it-to-your-elixir-project

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.1.1"}
  ]
End

using-within-livebook-and-iex

Using within LiveBook and IEx

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

LiveBook tour

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

Run in Livebook

documentation

Documentation

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