portmidi

README

portmidi

Want to output to an MIDI device or listen your MIDI device as an input? This package contains Go bindings for PortMidi. libportmidi (v. 217) is required as a dependency, it's available via apt-get and brew.

apt-get install libportmidi-dev
# or
brew install portmidi

Or, alternatively you can download the source and build it by yourself. See the instructions on PortMidi homepage.

In order to start, go get this repository:

go get github.com/rakyll/portmidi

Usage

Initialize

portmidi.Initialize()

About MIDI Devices

portmidi.CountDevices() // returns the number of MIDI devices
portmidi.Info(deviceID) // returns info about a MIDI device
portmidi.DefaultInputDeviceID() // returns the ID of the system default input
portmidi.DefaultOutputDeviceID() // returns the ID of the system default output

Write to a MIDI Device

out, err := portmidi.NewOutputStream(deviceID, 1024, 0)
if err != nil {
    log.Fatal(err)
}

// note on events to play C major chord
out.WriteShort(0x90, 60, 100)
out.WriteShort(0x90, 64, 100)
out.WriteShort(0x90, 67, 100)

// notes will be sustained for 2 seconds
time.Sleep(2 * time.Second)

// note off events
out.WriteShort(0x80, 60, 100)
out.WriteShort(0x80, 64, 100)
out.WriteShort(0x80, 67, 100)

out.Close()

Read from a MIDI Device

in, err := portmidi.NewInputStream(deviceID, 1024)
if err != nil {
    log.Fatal(err)
}
defer in.Close()

events, err := in.Read(1024)
if err != nil {
    log.Fatal(err)
}

// alternatively you can filter the input to listen
// only a particular set of channels
in.SetChannelMask(portmidi.Channel(1) | portmidi.Channel.(2))
in.Read(1024) // will retrieve events from channel 1 and 2

// or alternatively listen events
ch := in.Listen()
event := <-ch

Cleanup

Cleanup your input and output streams once you're done. Likely to be called on graceful termination.

portmidi.Terminate()

Documentation

Overview

Package portmidi provides PortMidi bindings.

Copyright 2013 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Variables
• func CountDevices() int
• func Initialize() error
• func Terminate() error
• type Channel
• type DeviceID
  • func DefaultInputDeviceID() DeviceID
  • func DefaultOutputDeviceID() DeviceID
• type DeviceInfo
  • func Info(deviceID DeviceID) *DeviceInfo
• type Event
• type Filter
• type Stream
  • func NewInputStream(id DeviceID, bufferSize int64) (stream *Stream, err error)
  • func NewOutputStream(id DeviceID, bufferSize int64, latency int64) (stream *Stream, err error)
  • func (s *Stream) Abort() error
  • func (s *Stream) Close() error
  • func (s *Stream) HasHostError() error
  • func (s *Stream) Listen() <-chan Event
  • func (s *Stream) Poll() (bool, error)
  • func (s *Stream) Read(max int) (events []Event, err error)
  • func (s *Stream) SetChannelMask(mask int) error
  • func (s *Stream) SetFilter(filters int) error
  • func (s *Stream) Write(events []Event) error
  • func (s *Stream) WriteShort(status int64, data1 int64, data2 int64) error
  • func (s *Stream) WriteSysEx(when Timestamp, msg string) error
  • func (s *Stream) WriteSysExBytes(when Timestamp, msg []byte) error
• type Timestamp
  • func Time() Timestamp

Examples

• Stream.Poll
• Stream.WriteShort
• Stream.WriteSysEx
• Stream.WriteSysExBytes

Variables

var (
	ErrMaxBuffer         = errors.New("portmidi: max event buffer size is 1024")
	ErrMinBuffer         = errors.New("portmidi: min event buffer size is 1")
	ErrInputUnavailable  = errors.New("portmidi: input is unavailable")
	ErrOutputUnavailable = errors.New("portmidi: output is unavailable")
	ErrSysExOverflow     = errors.New("portmidi: SysEx message overflowed")
)

var FILTER_ACTIVE = C.PM_FILT_ACTIVE

var FILTER_AFTERTOUCH = C.PM_FILT_AFTERTOUCH

var FILTER_CHANNEL_AFTERTOUCH = C.PM_FILT_CHANNEL_AFTERTOUCH

var FILTER_CLOCK = C.PM_FILT_CLOCK

var FILTER_CONTROL = C.PM_FILT_CONTROL

var FILTER_FD = C.PM_FILT_FD

var FILTER_MTC = C.PM_FILT_MTC

var FILTER_NOTE = C.PM_FILT_NOTE

var FILTER_PITCHBEND = C.PM_FILT_PITCHBEND

var FILTER_PLAY = C.PM_FILT_PLAY

var FILTER_POLY_AFTERTOUCH = C.PM_FILT_POLY_AFTERTOUCH

var FILTER_PROGRAM = C.PM_FILT_PROGRAM

var FILTER_REALTIME = C.PM_FILT_REALTIME

var FILTER_RESET = C.PM_FILT_RESET

var FILTER_SONG_POSITION = C.PM_FILT_SONG_POSITION

var FILTER_SONG_SELECT = C.PM_FILT_SONG_SELECT

var FILTER_SYSEX = C.PM_FILT_SYSEX

var FILTER_SYSTEMCOMMON = C.PM_FILT_SYSTEMCOMMON

var FILTER_TICK = C.PM_FILT_TICK

var FILTER_TUNE = C.PM_FILT_TUNE

var FILTER_UNDEFINED = C.PM_FILT_UNDEFINED

Functions

func CountDevices

func CountDevices() int

CountDevices returns the number of MIDI devices.

func Initialize

func Initialize() error

Initialize initializes the portmidi. Needs to be called before making any other call from the portmidi package. Once portmidi package is no longer required, Terminate should be called to free the underlying resources.

func Terminate

func Terminate() error

Terminate terminates and cleans up the midi streams.

Types

type Channel

type Channel int

Channel represent a MIDI channel. It should be between 1-16.

type DeviceID

type DeviceID int

DeviceID is a MIDI device ID.

func DefaultInputDeviceID

func DefaultInputDeviceID() DeviceID

DefaultInputDeviceID returns the default input device's ID.

func DefaultOutputDeviceID

func DefaultOutputDeviceID() DeviceID

DefaultOutputDeviceID returns the default output device's ID.

type DeviceInfo

type DeviceInfo struct {
	Interface         string
	Name              string
	IsInputAvailable  bool
	IsOutputAvailable bool
	IsOpened          bool
}

DeviceInfo provides info about a MIDI device.

func Info

func Info(deviceID DeviceID) *DeviceInfo

Info returns the device info for the device indentified with deviceID. If deviceID is out of range, Info returns nil.

type Event

type Event struct {
	Timestamp Timestamp
	Status    int64
	Data1     int64
	Data2     int64
	Rest      int64
}

Event represents a MIDI event.

type Filter

type Filter int

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

Stream represents a portmidi stream.

func NewInputStream

func NewInputStream(id DeviceID, bufferSize int64) (stream *Stream, err error)

NewInputStream initializes a new input stream.

func NewOutputStream

func NewOutputStream(id DeviceID, bufferSize int64, latency int64) (stream *Stream, err error)

NewOutputStream initializes a new output stream.

func (*Stream) Abort

func (s *Stream) Abort() error

Abort aborts the MIDI stream.

func (*Stream) Close

func (s *Stream) Close() error

Close closes the MIDI stream.

func (*Stream) HasHostError

func (s *Stream) HasHostError() error

HasHostError returns an async host error

func (*Stream) Listen

func (s *Stream) Listen() <-chan Event

Listen input stream for MIDI events.

func (*Stream) Poll

func (s *Stream) Poll() (bool, error)

Poll reports whether there is input available in the stream.

Example

package main

import (
	"fmt"
	"log"

	"github.com/rakyll/portmidi"
)

func main() {
	in, err := portmidi.NewInputStream(portmidi.DefaultInputDeviceID(), 1024)
	if err != nil {
		log.Fatal(err)
	}

	result, err := in.Poll()
	if err != nil {
		log.Fatal(err)
	}

	if result {
		fmt.Println("New messages in the queue!")
	} else {
		fmt.Println("No new messages in the queue :(")
	}
}

func (*Stream) Read

func (s *Stream) Read(max int) (events []Event, err error)

Reads from the input stream, the max number events to be read are determined by max.

func (*Stream) SetChannelMask

func (s *Stream) SetChannelMask(mask int) error

SetChannelMask filters incoming stream based on channel. In order to filter from more than a single channel, or multiple channels. s.SetChannelMask(Channel(1) | Channel(10)) will both filter input from channel 1 and 10.

func (*Stream) SetFilter

func (s *Stream) SetFilter(filters int) error

func (*Stream) Write

func (s *Stream) Write(events []Event) error

Write writes a buffer of MIDI events to the output stream.

func (*Stream) WriteShort

func (s *Stream) WriteShort(status int64, data1 int64, data2 int64) error

WriteShort writes a MIDI event of three bytes immediately to the output stream.

Example

package main

import (
	"log"
	"time"

	"github.com/rakyll/portmidi"
)

func main() {
	out, err := portmidi.NewOutputStream(portmidi.DefaultOutputDeviceID(), 1024, 0)
	if err != nil {
		log.Fatal(err)
	}

	// Send "note on" events to play C major chord.
	out.WriteShort(0x90, 60, 100)
	out.WriteShort(0x90, 64, 100)
	out.WriteShort(0x90, 67, 100)

	// Notes will be sustained for 2 seconds.
	time.Sleep(2 * time.Second)

	// Note off events.
	out.WriteShort(0x80, 60, 100)
	out.WriteShort(0x80, 64, 100)
	out.WriteShort(0x80, 67, 100)

	out.Close()
}

func (*Stream) WriteSysEx

func (s *Stream) WriteSysEx(when Timestamp, msg string) error

WriteSysEx writes a system exclusive MIDI message given as a string of hexadecimal characters to the output stream. The string must only consist of hex digits (0-9A-F) and optional spaces. This function is case-insenstive.

Example

package main

import (
	"log"

	"github.com/rakyll/portmidi"
)

func main() {
	out, err := portmidi.NewOutputStream(portmidi.DefaultOutputDeviceID(), 1024, 0)
	if err != nil {
		log.Fatal(err)
	}

	if err = out.WriteSysEx(portmidi.Time(), "F0 0A 0A 1B 00 7F 30 F7"); err != nil {
		log.Fatal(err)
	}
}

func (*Stream) WriteSysExBytes

func (s *Stream) WriteSysExBytes(when Timestamp, msg []byte) error

WriteSysExBytes writes a system exclusive MIDI message given as a []byte to the output stream.

Example

package main

import (
	"log"

	"github.com/rakyll/portmidi"
)

func main() {
	out, err := portmidi.NewOutputStream(portmidi.DefaultOutputDeviceID(), 1024, 0)
	if err != nil {
		log.Fatal(err)
	}

	if err = out.WriteSysExBytes(portmidi.Time(), []byte{0xF0, 0x0A, 0x0A, 0x1B, 0x00, 0x7F, 0x30, 0xF7}); err != nil {
		log.Fatal(err)
	}
}

type Timestamp

type Timestamp int64

func Time

func Time() Timestamp

Time returns the portmidi timer's current time.