Class NPlugMidiLearn

Namespace

PluginUI.NPlug

Assembly

PluginUI.NPlug.dll

IMidiLearnService on top of the VST3 MIDI mapping of a controller: the host turns the assigned MIDI controllers into parameter changes (IMidiMapping), learning listens to the live controllers the host reports (IMidiLearn::onLiveMIDIControllerInput). Created by PluginUIController<TModel>, which saves the assignments with the controller state.

public sealed class NPlugMidiLearn : IMidiLearnService

Inheritance

object

NPlugMidiLearn

Implements

IMidiLearnService

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Learning needs a host that reports live MIDI controllers (VST3 IMidiLearn, e.g. Cubase and Nuendo); in other hosts the learn entry stays pending until cancelled and the host's own MIDI learn remains available. Assignments are per MIDI channel unless LearnOnAllChannels is set, and take precedence over the fixed mappings declared with SetMidiCCMapping. All members run on the UI thread.

Constructors

NPlugMidiLearn(Func<IAudioControllerHandler?>)

Creates the service.

public NPlugMidiLearn(Func<IAudioControllerHandler?> handler)

Parameters

handler Func<IAudioControllerHandler>

Returns the host handler (used to notify mapping changes); may return null.

Properties

Assignments

Learned assignments: (channel, controller) → parameter; channel −1 means every channel.

public IReadOnlyDictionary<(int Channel, int Controller), AudioParameterId> Assignments { get; }

Property Value

IReadOnlyDictionary<(int Channel, int Controller), AudioParameterId>

LearnOnAllChannels

When true, a learned controller applies to every MIDI channel (default: only the channel it came from).

public bool LearnOnAllChannels { get; set; }

Property Value

bool

LearningParameter

Parameter waiting for a controller, or null.

public AudioParameterId? LearningParameter { get; }

Property Value

AudioParameterId?

Methods

Assign(AudioParameterId, int, int)

Assigns a controller to a parameter, replacing the previous assignment of that controller.

public void Assign(AudioParameterId parameter, int channel, int controller)

Parameters

parameter AudioParameterId

The parameter id.

channel int

MIDI channel, 0-based, or −1 for every channel.

controller int

Controller number: 0..127, 128 (aftertouch) or 129 (pitch bend).

Exceptions

ArgumentOutOfRangeException

The channel or the controller is out of range.

BeginLearn(IParameter)

Starts learning for a parameter (cancels any other learn in progress).

public void BeginLearn(IParameter parameter)

Parameters

parameter IParameter

The parameter to assign to the next MIDI controller moved.

CancelLearn()

Cancels the learn in progress, if any.

public void CancelLearn()

Clear()

Removes every assignment.

public void Clear()

Describe(int, int)

Text of an assignment ("CC 74 · Ch 1", "Pitch Bend", channel −1 = every channel).

public static string Describe(int channel, int controller)

Parameters

channel int

MIDI channel, 0-based, or −1.

controller int

Controller number.

Returns

string

The description.

Forget(AudioParameterId)

Removes every assignment of a parameter.

public void Forget(AudioParameterId parameter)

Parameters

parameter AudioParameterId

The parameter id.

Forget(IParameter)

Removes the MIDI assignment of a parameter.

public void Forget(IParameter parameter)

Parameters

parameter IParameter

A parameter.

GetAssignment(IParameter)

Short description of the assignment (e.g. "CC 74 · Ch 1"), or null if the parameter has none.

public string? GetAssignment(IParameter parameter)

Parameters

parameter IParameter

A parameter.

Returns

string

The assignment text, or null.

IsLearning(IParameter)

true while parameter waits for a MIDI controller.

public bool IsLearning(IParameter parameter)

Parameters

parameter IParameter

A parameter.

Returns

bool

true if learning for this parameter.

Load(PortableBinaryReader)

Reads assignments written by Save(PortableBinaryWriter). A state without them (saved by an older version of the plug-in) leaves the service empty and, when the stream can seek, the stream where it was.

public bool Load(PortableBinaryReader reader)

Parameters

reader PortableBinaryReader

The reader.

Returns

bool

true if assignments were found.

OnLiveController(int, int, AudioMidiControllerNumber)

Live controller reported by the host: completes a learn in progress.

public bool OnLiveController(int busIndex, int channel, AudioMidiControllerNumber controller)

Parameters

busIndex int

Event input bus.

channel int

MIDI channel, 0-based.

controller AudioMidiControllerNumber

Controller number.

Returns

bool

true if the controller was used (the assignment changed).

Save(PortableBinaryWriter)

Writes the assignments (controller state).

public void Save(PortableBinaryWriter writer)

Parameters

writer PortableBinaryWriter

The writer.

TryGetAssignment(int, int, AudioMidiControllerNumber, out AudioParameterId)

Parameter assigned to a controller on a channel (IMidiMapping query).

public bool TryGetAssignment(int busIndex, int channel, AudioMidiControllerNumber controller, out AudioParameterId parameter)

Parameters

busIndex int

Event input bus.

channel int

MIDI channel, 0-based.

controller AudioMidiControllerNumber

Controller number.

parameter AudioParameterId

The assigned parameter.

Returns

bool

true if a learned assignment exists.

Events

Changed

Raised when a learn starts, ends, or an assignment changes.

public event Action? Changed

Event Type

Action