connect

README

connect

Go interface for MIDI drivers

Purpose

Unification of MIDI driver packages for Go. Currently two implementations exist:

• for rtmidi: https://github.com/gomidi/rtmididrv
• for portmidi: https://github.com/gomidi/portmididrv

This package is also used by https://github.com/gomidi/mid for smooth integration

Installation

It is recommended to use Go 1.11 with module support ($GO111MODULE=on).

For rtmidi (see https://github.com/thestk/rtmidi for more information)

// install the headers of alsa somehow, e.g. sudo apt-get install libasound2-dev
go get -d github.com/gomidi/rtmididrv

For portaudio (see https://github.com/rakyll/portmidi for more information)

// install the headers of portmidi somehow, e.g. sudo apt-get install libportmidi-dev
go get -d github.com/gomidi/portmididrv

Documentation

rtmididrv:

portmididrv:

Example

package main

import (
	"fmt"
	"os"
	"time"

	"github.com/gomidi/connect"
	"github.com/gomidi/mid"
	driver "github.com/gomidi/rtmididrv"
	// for portmidi
	// driver "github.com/gomidi/portmididrv" 
)

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

// This example expects the first input and output port to be connected
// somehow (are either virtual MIDI through ports or physically connected).
// We write to the out port and listen to the in port.
func main() {
	drv, err := driver.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 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())

	wr := mid.WriteTo(out)

	// listen for MIDI
	go mid.NewReader().ReadFrom(in)

	{ // write MIDI to out that passes it to in on which we listen.
		err := wr.NoteOn(60, 100)
		if err != nil {
			panic(err)
		}
		time.Sleep(time.Nanosecond)
		wr.NoteOff(60)
		time.Sleep(time.Nanosecond)

		wr.SetChannel(1)

		wr.NoteOn(70, 100)
		time.Sleep(time.Nanosecond)
		wr.NoteOff(70)
		time.Sleep(time.Second * 1)
	}
}

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

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

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

Documentation

Index

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

Variables

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

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

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
	// println(big.NewRat(math.MaxInt64,1000 /* milliseonds */ *1000 /* seconds */ *60 /* minutes */ *60 /* hours */ *24 /* days */ *365 /* years */).FloatString(0))
	// output: 292471
	// => a ascending timestamp based on microseconds would wrap after 292471 years
	SetListener(func(data []byte, deltaMicroseconds int64)) error

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

In is an interface for a MIDI in port

func OpenIn

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

OpenIn opens a MIDI 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 Out

type Out interface {
	Port

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

Out is an interface for a MIDI out port

func OpenOut

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

OpenOut opens a MIDI 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.
	// outport
	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 use user must take care of proper opening/closing etc.
	Underlying() interface{}
}

Port is an interface for a MIDI port