midi

README

midi

Modular library for reading and writing of MIDI messages and MIDI files with Go.

Note: If you are reading this on Github, please note that the repo has moved to Gitlab (gitlab.com/gomidi/midi) and this is only a mirror.

Status

stable

• Go version: >= 1.12
• OS/architectures: everywhere Go runs (tested on Linux and Windows).

Installation

go get gitlab.com/gomidi/midi@latest

Features

This package provides a unified way to read and write "over the wire" MIDI data and MIDI files (SMF).

• implementation of complete MIDI standard (live and SMF data)
• reading and optional writing with "running status"
• seamless integration with io.Reader and io.Writer
• allows the reuse of same libraries for live writing and writing to SMF files
• provide building blocks for other MIDI libraries and applications
• stable API
• no dependencies outside the standard library
• small modular core packages
• typed Messages

Non-Goals

• constructing of MIDI time code messages
• Multidimensional Polyphonic Expression (MPE)
• dealing with the inner structure of sysex messages
• CLI tools

Drivers

For "over the wire" communication you need a Driverto connect with the MIDI system of your OS. Currently there are two multi-platform drivers available:

• package gitlab.com/gomidi/rtmididrv based on rtmidi
• package gitlab.com/gomidi/portmididrv based on portmidi

Porcelain package

For easy access, the porcelain package gitlab.com/gomidi/midi/mid is recommended.

The other packages are more low level and allow you to write your own implementations of the midi.Reader, midi.Writerand midi.Driver interfaces to wrap the given SMF and live readers/writers/drivers for your own application.

Documentation porcelain package

Example with external MIDI gear

package main

import (
	"fmt"
	"os"

	"gitlab.com/gomidi/midi"
	"gitlab.com/gomidi/midi/mid"
	"gitlab.com/gomidi/rtmididrv"
)

// This example reads from the first input and and writes to the first output port
func main() {
	drv, err := rtmididrv.New()
	must(err)

	// make sure to close all open ports at the end
	defer drv.Close()

	ins, err := drv.Ins()
	must(err)

	outs, err := drv.Outs()
	must(err)

	// if the string `list` is passed as an argument,
	// print the available in and out ports
	if len(os.Args) == 2 && os.Args[1] == "list" {
		printInPorts(ins)
		printOutPorts(outs)
		return
	}

	in, out := ins[0], outs[0]

	must(in.Open())
	must(out.Open())

	defer in.Close()
	defer out.Close()

	// the writer we are writing to
	wr := mid.ConnectOut(out)

	// to disable logging, pass mid.NoLogger() as option
	rd := mid.NewReader()

	// write every message to the out port
	rd.Msg.Each = func(pos *mid.Position, msg midi.Message) {
		wr.Write(msg)
	}

	// listen for MIDI
	mid.ConnectIn(in, rd)
}

func printPort(port midi.Port) {
	fmt.Printf("[%v] %s\n", port.Number(), port.String())
}

func printInPorts(ports []midi.In) {
	fmt.Printf("MIDI IN Ports\n")
	for _, port := range ports {
		printPort(port)
	}
	fmt.Printf("\n\n")
}

func printOutPorts(ports []midi.Out) {
	fmt.Printf("MIDI OUT Ports\n")
	for _, port := range ports {
		printPort(port)
	}
	fmt.Printf("\n\n")
}

func must(err error) {
	if err != nil {
		panic(err.Error())
	}
}

Example with io.Writer and io.Reader

A simple example with "live" MIDI and io.Reader and io.Writer.

We use an io.Writer to write to and io.Reader to read from. They are connected by the same io.Pipe.

package main

import (
	"fmt"
	"io"
	"time"

	"gitlab.com/gomidi/midi/mid"
)

// callback for note on messages
func noteOn(p *mid.Position, channel, key, vel uint8) {
	fmt.Printf("NoteOn (ch %v: key %v vel: %v)\n", channel, key, vel)
}

// callback for note off messages
func noteOff(p *mid.Position, channel, key, vel uint8) {
	fmt.Printf("NoteOff (ch %v: key %v)\n", channel, key)
}

func main() {
	fmt.Println()

	// to disable logging, pass mid.NoLogger() as option
	rd := mid.NewReader()

	// set the functions for the messages you are interested in
	rd.Msg.Channel.NoteOn = noteOn
	rd.Msg.Channel.NoteOff = noteOff

	// to allow reading and writing concurrently in this example
	// we need a pipe
	piperd, pipewr := io.Pipe()

	go func() {
		wr := mid.NewWriter(pipewr)
		wr.SetChannel(11) // sets the channel for the next messages
		wr.NoteOn(120, 50)
		time.Sleep(time.Second) // let the note ring for 1 sec
		wr.NoteOff(120)
		pipewr.Close() // finishes the writing
	}()

	for {
		if rd.ReadAllFrom(piperd) == io.EOF {
			piperd.Close() // finishes the reading
			break
		}
	}

	// Output:
	// channel.NoteOn channel 11 key 120 velocity 50
	// NoteOn (ch 11: key 120 vel: 50)
	// channel.NoteOff channel 11 key 120
	// NoteOff (ch 11: key 120)
}

Low level packages

Documentation main package

Example with low level packages

package main

import (
    "bytes"
    "fmt"
    . "gitlab.com/gomidi/midi/midimessage/channel"
    "gitlab.com/gomidi/midi/midimessage/realtime"
    "gitlab.com/gomidi/midi/midireader"
    "gitlab.com/gomidi/midi/midiwriter"
    "io"
    "gitlab.com/gomidi/midi"
)

func main() {
    var bf bytes.Buffer

    wr := midiwriter.New(&bf)
    wr.Write(Channel2.Pitchbend(5000))
    wr.Write(Channel2.NoteOn(65, 90))
    wr.Write(realtime.Reset)
    wr.Write(Channel2.NoteOff(65))

    rthandler := func(m realtime.Message) {
        fmt.Printf("Realtime: %s\n", m)
    }

    rd := midireader.New(bytes.NewReader(bf.Bytes()), rthandler)

    var m midi.Message
    var err error

    for {
        m, err = rd.Read()

        // breaking at least with io.EOF
        if err != nil {
            break
        }

        // inspect
        fmt.Println(m)

        switch v := m.(type) {
        case NoteOn:
            fmt.Printf("NoteOn at channel %v: key: %v velocity: %v\n", v.Channel(), v.Key(), v.Velocity())
        case NoteOff:
            fmt.Printf("NoteOff at channel %v: key: %v\n", v.Channel(), v.Key())
        }

    }

    if err != io.EOF {
        panic("error: " + err.Error())
    }

    // Output:
    // channel.Pitchbend channel 2 value 5000 absValue 13192
    // channel.NoteOn channel 2 key 65 velocity 90
    // NoteOn at channel 2: key: 65 velocity: 90
    // Realtime: Reset
    // channel.NoteOff channel 2 key 65
    // NoteOff at channel 2: key: 65
}

Modularity

Apart from the porcelain package there are small subpackages, so that you only need to import what you really need.

This keeps packages and dependencies small, better testable and should result in a smaller memory footprint which should help smaller devices.

For reading and writing of live and SMF MIDI data io.Readers are accepted as input and io.Writers as output. Furthermore there are common interfaces for live and SMF MIDI data handling: midi.Reader and midi.Writer. The typed MIDI messages used in each case are the same.

To connect with MIDI libraries expecting and returning plain bytes, use the midiio subpackage.

License

MIT (see LICENSE file)

Credits

Inspiration and low level code for MIDI reading (see internal midilib package) came from the http://github.com/afandian/go-midi package of Joe Wass which also helped as a starting point for the reading of SMF files.

Alternatives

Matt Aimonetti is also working on MIDI inside https://github.com/mattetti/audio but I didn't try it.

Documentation

Overview

Package midi provides interfaces for reading and writing of MIDI messages.

Since they are handled slightly different, this packages introduces the terminology of "live" MIDI reading/writing for dealing with MIDI messages as "over the wire" (in realtime) as opposed to smf MIDI reading/writing to Standard MIDI Files (SMF).

However both variants can be used with io.Writer and io.Reader and can thus be "streamed".

This package provides a Reader and Writer interface that is common to live and SMF MIDI handling. This should allow to easily develop transformations (e.g. quantization, filtering) that may be used in both cases.

If you want a comfortable common package providing everything at a high level, use the porcelain package

gitlab.com/gomidi/midi/mid

The underlying core implementations can be found here:

gitlab.com/gomidi/midi/midireader (live reading)
gitlab.com/gomidi/midi/midiwriter (live writing)
gitlab.com/gomidi/midi/smf/smfreader   (SMF reading)
gitlab.com/gomidi/midi/smf/smfwriter   (SMF writing)
gitlab.com/gomidi/midi/smf/smftrack    (SMF modification)

The core of the MIDI messages that can be written or analyzed can be found here:

gitlab.com/gomidi/midi/midimessage/channel    (Channel Messages)
gitlab.com/gomidi/midi/midimessage/meta       (Meta Messages)
gitlab.com/gomidi/midi/midimessage/realtime   (System Realtime Messages)
gitlab.com/gomidi/midi/midimessage/syscommon  (System Common messages)
gitlab.com/gomidi/midi/midimessage/sysex      (System Exclusive messages)

Please keep in mind that that not all kinds of MIDI messages can be used in both scenarios.

System Realtime and System Common Messages are restricted to "over the wire", while Meta Messages are restricted to SMF files. However System Realtime and System Common Messages can be saved inside a SMF file which the help of SysEx escaping (F7).

Index

• Variables
• type Driver
• type In
  • func OpenIn(d Driver, number int, name string) (in In, err error)
• type Message
• type Out
  • func OpenOut(d Driver, number int, name string) (out Out, err error)
• type Port
• type ReadCloser
• type Reader
• type WriteCloser
• type Writer

Variables

var ErrPortClosed = fmt.Errorf("ERROR: port is closed")

ErrPortClosed should be returned from a driver when trying to write to a closed port.

var ErrUnexpectedEOF = fmt.Errorf("Unexpected End of File found.")

ErrUnexpectedEOF is returned, when an unexspected end of file is reached.

Types

type Driver

type Driver interface {

	// Ins returns the available MIDI input ports.
	Ins() ([]In, error)

	// Outs returns the available MIDI output ports.
	Outs() ([]Out, error)

	// String returns the name of the driver.
	String() string

	// Close closes the driver. Must be called for cleanup at the end of a session.
	Close() error
}

Driver is a driver for MIDI connections.

type In

type In interface {
	Port

	// SetListener sets the callback function that is called when data arrives.
	SetListener(func(data []byte, deltaMicroseconds int64)) error

	// StopListening stops the listening.
	// When closing a MIDI input port, StopListening must be called before (from the driver).
	StopListening() error
}

In is an interface for a MIDI input port

func OpenIn

func OpenIn(d Driver, number int, name string) (in In, err error)

OpenIn opens a MIDI input port with the help of the given driver. To find the port by port number, pass a number >= 0. To find the port by port name, pass a number < 0 and a non empty string.

type Message

type Message interface {

	// String inspects the MIDI message in an informative way.
	String() string

	// Raw returns the raw bytes of the MIDI message.
	Raw() []byte
}

Message is a MIDI message.

type Out

type Out interface {
	Port

	// Send sends the given MIDI bytes over the wire.
	// If the port is closed, ErrPortClosed must be returned.
	Send([]byte) error
}

Out is an interface for a MIDI output port.

func OpenOut

func OpenOut(d Driver, number int, name string) (out Out, err error)

OpenOut opens a MIDI output port with the help of the given driver. To find the port by port number, pass a number >= 0. To find the port by port name, pass a number < 0 and a non empty string.

type Port

type Port interface {

	// Open opens the MIDI port. An implementation should save the open state to make it
	// save to call open when the port is already open without getting an error.
	Open() error

	// Close closes the MIDI port. An implementation should save the open state to make it
	// save to call close when the port is already closed without getting an error.
	Close() error

	// IsOpen returns wether the MIDI port is open.
	IsOpen() bool

	// Number returns the number of the MIDI port. It is only guaranteed that the numbers are unique within
	// MIDI port groups i.e. within MIDI input ports and MIDI output ports. So there may be the same number
	// for a given MIDI input port and some MIDI output port. Or not - that depends on the underlying driver.
	Number() int

	// String represents the MIDI port by a string, aka name.
	String() string

	// Underlying returns the underlying driver to allow further adjustments.
	// When using the underlying driver, the user must take care of proper opening/closing etc.
	Underlying() interface{}
}

Port is an interface for a MIDI port.

type ReadCloser

type ReadCloser interface {
	Reader
	Close() error
}

ReadCloser is a Reader that must be closed at the end of reading.

type Reader

type Reader interface {

	// Read reads a MIDI message.
	Read() (Message, error)
}

Reader reads MIDI messages.

type WriteCloser

type WriteCloser interface {
	Writer
	Close() error
}

WriteCloser is a Writer that must be closed at the end of writing.

type Writer

type Writer interface {

	// Write writes the given MIDI message and returns any error.
	Write(Message) error
}

Writer writes MIDI messages.