Platforms to show: All Mac Windows Linux Cross-Platform

Back to PortMidiStreamMBS class.

PortMidiStreamMBS.Abort as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Terminates outgoing messages immediately.

The caller should immediately close the output port; this call may result in transmission of a partial midi message. There is no abort for Midi input because the user can simply ignore messages in the buffer and close an input device at any time.
Returns an error code.

PortMidiStreamMBS.Close

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
The destructor.

There is no need to call this method except you want to free all resources of this object now without waiting for Xojo to do it for you.

PortMidiStreamMBS.ErrorText(ErrorNumber as Integer) as string

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
The error message for this error number.

PortMidiStreamMBS.HostError as string

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 13.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Queries host error string.
Example
dim s as new PortMidiStreamMBS
// do something that causes an error
MsgBox "HostError: "+s.HostError

Clears error.

PortMidiStreamMBS.OpenInput(DeviceID as Integer, Buffersize as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Opens a device for reading.

DeviceID is the id of the device used for input.

For input, the buffersize specifies the number of input events to be buffered waiting to be read using Pm_Read().
(In some cases -- see below -- PortMidi does not buffer output at all and merely passes data to a lower-level API, in which case buffersize is ignored.)

return value:
Upon success OpenInput returns PmNoError.
If a call to OpenInput fails a nonzero error code is returned (see PMError above) and the value of port is invalid.

Some examples using this method:

PortMidiStreamMBS.OpenOutput(DeviceID as Integer, Buffersize as Integer, Latency as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Opens a device for writing.

DeviceID is the id of the device used for input.

For output, buffersize specifies the number of output events to be buffered waiting for output.
(In some cases -- see below -- PortMidi does not buffer output at all and merely passes data to a lower-level API, in which case buffersize is ignored.)

Latency is the delay in milliseconds applied to timestamps to determine when the output should actually occur. (If latency is < 0, 0 is assumed.)
If latency is zero, timestamps are ignored and all output is delivered immediately. If latency is greater than zero, output is delayed until the message timestamp plus the latency. (NOTE: time is measured relative to the time source indicated by time_proc. Timestamps are absolute, not relative delays or offsets.) In some cases, PortMidi can obtain better timing than your application by passing timestamps along to the device driver or hardware. Latency may also help you to synchronize midi data to audio data by matching midi latency to the audio buffer latency.
Due to the may timers work on Windows, the latency is limited there.

return value:
Upon success OpenInput returns PmNoError.
If a call to OpenInput fails a nonzero error code is returned (see PMError above) and the value of port is invalid.

Some examples using this method:

PortMidiStreamMBS.Poll as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Tests whether input is available,

Returns 1 on success and 0 on failure.

PortMidiStreamMBS.Read(byref data as PortMidiEventMBS) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Reads midi data.

Returns the number of read items.
(0 for error and 1 for success)

Read retrieves midi data into a buffer, and returns the number of events read. Result is a non-negative number unless an error occurs, in which case a PmError value will be returned.

Buffer Overflow

The problem: if an input overflow occurs, data will be lost, ultimately because there is no flow control all the way back to the data source. When data is lost, the receiver should be notified and some sort of graceful recovery should take place, e.g. you shouldn't resume receiving in the middle of a long sysex message.

With a lock-free fifo, which is pretty much what we're stuck with to enable portability to the Mac, it's tricky for the producer and consumer to synchronously reset the buffer and resume normal operation.

Solution: the buffer managed by PortMidi will be flushed when an overflow occurs. The consumer (Read()) gets an error message (pmBufferOverflow) and ordinary processing resumes as soon as a new message arrives. The remainder of a partial sysex message is not considered to be a "new message" and will be flushed as well.

PortMidiStreamMBS.SetChannelMask(mask as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Filters incoming messages based on channel.
Example
dim s as PortMidiStreamMBS // your midi stream

call s.SetChannelMask(1+4) // Channel 1 and 3.

The mask is a 16-bit bitfield corresponding to appropriate channels
All channels are allowed by default.
Returns an error code.

PortMidiStreamMBS.SetFilter(filters as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
SetFilter() sets filters on an open input stream to drop selected input types.

By default, only active sensing messages are filtered.
To prohibit, say, active sensing and sysex messages, call SetFilter(FilterActive + FilterSysEx);

Filtering is useful when midi routing or midi thru functionality is being provided by the user application.
For example, you may want to exclude timing messages (clock, MTC, start/stop/continue), while allowing note-related messages to pass.
Or you may be using a sequencer or drum-machine for MIDI clock information but want to exclude any notes it may play.

Returns an error code.

PortMidiStreamMBS.Write(data as PortMidiEventMBS) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Writes midi data from a buffer.

This may contain:
- short messages or
- sysex messages that are converted into a sequence of PortMidiStreamMBS objects, e.g. sending data from a file or forwarding them from midi input.

Use WriteSysEx() to write a sysex message stored as a contiguous array of bytes.

Sysex data may contain embedded real-time messages.
Returns an error code.

PortMidiStreamMBS.WriteShort(When as Integer, message as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Writes a timestamped non-system-exclusive midi message.

Messages are delivered in order as received, and timestamps must be non-decreasing. (But timestamps are ignored if the stream was opened with latency = 0.)

PortMidiStreamMBS.WriteSysEx(When as Integer, message as memoryblock, offset as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 9.1 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Writes a timestamped system-exclusive midi message.

The data is taken from the memoryblock at the given offset.
The message must be 0 terminated.

This message must be valid and contain the special start value and a EOX value on the end.

See also:

PortMidiStreamMBS.WriteSysEx(When as Integer, message as string) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method MIDI MBS Audio Plugin 5.2 ✅ Yes ✅ Yes ✅ Yes ✅ Yes All
Writes a timestamped system-exclusive midi message.

This message must be valid and contain the special start value and a EOX value on the end.

See also:

The items on this page are in the following plugins: MBS Audio Plugin.


The biggest plugin in space...