max

README

max-go

Toolkit for building Max externals with Go.

Installation

First you need to ensure you have recent version of Go installed. On macOS simply install it using brew:

brew install go

Then you can install the package and CLI using Go's module management:

go get -u github.com/256dpi/max-go
go get -u github.com/256dpi/max-go/cmd/maxgo

This will install the maxgo command line utility. You may need to add Go's bin directory tou your PATH variable to access the CLI in the terminal:

echo 'export PATH=~/go/bin:$PATH' >> ~/.zprofile # for zsh

Cross compilation on macOS for Windows additionally requires the zig toolchain:

brew install zig

Usage

Add the following file to an empty directory:

package main

import  "github.com/256dpi/max-go"

type instance struct {
	in1   *max.Inlet
	in2   *max.Inlet
	out1  *max.Outlet
	out2  *max.Outlet
}

func (i *instance) Init(obj *max.Object, args []max.Atom) {
	// print to Max console
	max.Pretty("init", args)

	// declare inlets
	i.in1 = obj.Inlet(max.Any, "example inlet 1", true)
	i.in2 = obj.Inlet(max.Float, "example inlet 2", false)

	// declare outlets
	i.out1 = obj.Outlet(max.Any, "example outlet 1")
	i.out2 = obj.Outlet(max.Bang, "example outlet 2")
}

func (i *instance) Handle(inlet int, msg string, data []max.Atom) {
	// print to Max console
	max.Pretty("handle", inlet, msg, data)

	// send to first outlet
	i.out1.Any(msg, data)
}

func (i *instance) Free() {
	// print to Max console
	max.Pretty("free")
}

func init() {
	// initialize Max class
	max.Register("example", &instance{})
}

func main() {
	// not called
}

Compile the external to the dist directory:

maxgo -name example -out dist

You can also cross compile (macOS only) and install the external:

maxgo -name example -out dist -cross -install example

Documentation

Index

• func Alert(format string, args ...interface{})
• func Defer(fn func())
• func Error(format string, args ...interface{})
• func Init(name string, init InitCallback, handle HandleCallback, process ProcessCallback, ...)
• func IsMainThread() bool
• func Log(format string, args ...interface{})
• func Pretty(a ...interface{})
• func Register(name string, prototype Instance)
• func ToFloat(atom Atom) float64
• func ToInt(atom Atom) int64
• func ToString(atom Atom) string
• type AdvancedInstance
• type Atom
• type Event
• type FreeCallback
• type HandleCallback
• type InitCallback
• type Inlet
  • func (i *Inlet) Label() string
  • func (i *Inlet) Type() Type
• type Instance
• type Object
  • func (o *Object) Inlet(typ Type, label string, hot bool) *Inlet
  • func (o *Object) Outlet(typ Type, label string) *Outlet
  • func (o *Object) Push(events ...Event)
• type Outlet
  • func (o *Outlet) Any(msg string, atoms []Atom)
  • func (o *Outlet) Bang()
  • func (o *Outlet) Float(n float64)
  • func (o *Outlet) Int(n int64)
  • func (o *Outlet) Label() string
  • func (o *Outlet) List(atoms []Atom)
  • func (o *Outlet) Type() Type
• type ProcessCallback
• type ProcessingInstance
• type Type

Functions

func Alert

func Alert(format string, args ...interface{})

Alert will show an alert dialog.

func Defer

func Defer(fn func())

Defer will run the provided function on the Max main thread.

func Error

func Error(format string, args ...interface{})

Error will print an error to the max console.

func Init

func Init(name string, init InitCallback, handle HandleCallback, process ProcessCallback, free FreeCallback)

Init will initialize the Max class with the specified name using the provided callbacks to initialize and free objects. This function must be called from the main packages main() function.

The provided callbacks are called to initialize and object, handle messages, process audio and free the object when it is not used anymore. The callbacks are usually called on the Max main thread. However, the handler may be called from an unknown thread in parallel to the other callbacks.

func IsMainThread

func IsMainThread() bool

IsMainThread will return if the Max main thead is executing.

func Log

func Log(format string, args ...interface{})

Log will print a message to the max console.

func Pretty

func Pretty(a ...interface{})

Pretty will pretty print and log the provided values.

func Register

func Register(name string, prototype Instance)

Register will initialize the Max class using the provided instance. This function must be called from the main packages main() function. The instance methods are usually called on the Max main thread. However, the handler may be called from an unknown thread in parallel to the other callbacks.

func ToFloat

func ToFloat(atom Atom) float64

ToFloat will convert to float64.

func ToInt

func ToInt(atom Atom) int64

ToInt will convert to int64.

func ToString

func ToString(atom Atom) string

ToString will convert to string.

Types

type AdvancedInstance

type AdvancedInstance interface {
	Loaded()
	DoubleClicked()
}

AdvancedInstance is an object that responds to advanced messages.

type Atom

type Atom = interface{}

Atom is a Max atom of type int64, float64 or string.

type Event

type Event struct {
	Outlet *Outlet
	Type   Type
	Msg    string
	Data   []Atom
}

Event describes an emitted event.

type FreeCallback

type FreeCallback func(obj *Object)

FreeCallback is called to free objects.

type HandleCallback

type HandleCallback func(obj *Object, inlet int, name string, atoms []Atom)

HandleCallback is called to handle messages.

type InitCallback

type InitCallback func(obj *Object, atoms []Atom) bool

InitCallback is called to initialize objects.

type Inlet

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

Inlet is a single Max inlet.

func (*Inlet) Label

func (i *Inlet) Label() string

Label will return the inlets label.

func (*Inlet) Type

func (i *Inlet) Type() Type

Type will return the inlets type.

type Instance

type Instance interface {
	Init(obj *Object, args []Atom) bool
	Handle(inlet int, msg string, data []Atom)
	Free()
}

Instance is a generic object instance.

type Object

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

Object is single Max object.

func (*Object) Inlet

func (o *Object) Inlet(typ Type, label string, hot bool) *Inlet

Inlet will declare an inlet. If no inlets are added to an object it will have a default inlet to receive messages.

func (*Object) Outlet

func (o *Object) Outlet(typ Type, label string) *Outlet

Outlet will declare an outlet.

func (*Object) Push

func (o *Object) Push(events ...Event)

Push will add the provided events to the objects queue.

type Outlet

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

Outlet is a single MAx outlet.

func (*Outlet) Any

func (o *Outlet) Any(msg string, atoms []Atom)

Any will send any message.

func (*Outlet) Bang

func (o *Outlet) Bang()

Bang will send a bang.

func (*Outlet) Float

func (o *Outlet) Float(n float64)

Float will send a float.

func (*Outlet) Int

func (o *Outlet) Int(n int64)

Int will send and int.

func (*Outlet) Label

func (o *Outlet) Label() string

Label will return the outlets label.

func (*Outlet) List

func (o *Outlet) List(atoms []Atom)

List will send a list.

func (*Outlet) Type

func (o *Outlet) Type() Type

Type will return the outlets type.

type ProcessCallback

type ProcessCallback func(obj *Object, ins, outs [][]float64)

ProcessCallback is called to process audio.

type ProcessingInstance

type ProcessingInstance interface {
	Process(input, output [][]float64)
}

ProcessingInstance is an object that can processes audio.

type Type

type Type string

Type describes an inlet or outlet type.

const (
	Bang   Type = "bang"
	Int    Type = "int"
	Float  Type = "float"
	List   Type = "list"
	Any    Type = "any"
	Signal Type = "signal"
)

The available inlet and outlet types.