midi

README

midi

Reading and writing of MIDI messages with Go.

Goals

• implementation of complete MIDI standard (live and SMF data)
• provide building blocks for MIDI applications
• stable API
• no dependencies outside the standard library
• small modular core packages and a fat comfortable porcelain package
• pure Go library (no C, no assembler)

Non-Goals

• constructing of MIDI time code messages
• dealing with the inner structure of sysex messages
• connection to MIDI devices (combine this lib with http://github.com/rakyll/portmidi or http://github.com/scgolang/midi )
• CLI tools

Usage

Most users will want to use the porcelain package

go get -d -t github.com/gomidi/midi/mid

Docs:

You don't need to read here further, if you are not interested in the nitty gritty details.

Modularity

This package is divided into 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.

Perfomance

On my laptop, writing noteon and noteoff ("live")

BenchmarkSameChannel            123 ns/op  12 B/op  3 allocs/op
BenchmarkAlternatingChannel     123 ns/op  12 B/op  3 allocs/op
BenchmarkRunningStatusDisabled  110 ns/op  12 B/op  3 allocs/op

On my laptop, reading noteon and noteoff ("live") ("Samechannel" makes use of running status byte).

BenchmarkSameChannel            351 ns/op  12 B/op  7 allocs/op
BenchmarkAlternatingChannel     425 ns/op  14 B/op  9 allocs/op

Full Documentation

see http://godoc.org/github.com/gomidi/midi

Status

late beta - API mostly stable

• Supported Go versions: >= 1.2
• Supported OS/architecture: Should work on all OS/architectures that Go supports (is tested on Linux and Windows, but no OS specific code).

    package                   API stable          complete
    ----------------------------------------------------
    midiwriter                yes                 yes
    midireader                yes                 yes
    smf                       yes                 yes
    smf/smfwriter             yes                 yes
    smf/smfreader             yes                 yes
    midimessage/channel       yes                 yes
    midimessage/cc            yes                 yes
    midimessage/meta          yes                 yes
    midimessage/realtime      yes                 yes
    midimessage/syscommon     yes                 yes
    midimessage/sysex         no                  yes
    midiio                    yes                 yes
    
	------- porcelain packages -------
    smf/smftrack              no                  no
    mid                       almost              yes

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 procelain package

github.com/gomidi/midi/mid

The underlying core implementations can be found here:

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

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

github.com/gomidi/midi/midimessage/channel    (Channel Messages)
github.com/gomidi/midi/midimessage/cc         (Control Change Messages)
github.com/gomidi/midi/midimessage/meta       (Meta Messages)
github.com/gomidi/midi/midimessage/realtime   (System Realtime Messages)
github.com/gomidi/midi/midimessage/syscommon  (System Common messages)
github.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 Message
• type ReadCloser
• type Reader
• type WriteCloser
• type Writer

Variables

var ErrUnexpectedEOF = errors.New("Unexpected End of File found.")

Types

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 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 the number of written bytes and any error
	Write(Message) (nBytes int, err error)
}

Writer writes MIDI messages