Classes

This is currently undocumented. Documentation contributions are always welcome!

The mutable counterpart of MIKMIDIChannelEvent.

In MIKMIDI, MIDI messages are objects. Specifically, they are instances of MIKMIDICommand or one of its subclasses. MIKMIDICommand’s subclasses each represent a specific type of MIDI message, for example, control change command messages will be instances of MIKMIDIControlChangeCommand. MIKMIDICommand includes properties for getting information and data common to all MIDI messages. Its subclasses implement additional method and properties specific to messages of their associated type.

MIKMIDICommand is also available in mutable variants, most useful for creating commands to be sent out by your application.

To create a new command, typically, you should use +commandForCommandType:.

Subclass MIKMIDICommand

Support for the various MIDI message types is provided by type-specific subclasses of MIKMIDICommand. For example, Control Change messages are represented using MIKMIDIControlChangeCommand. MIKMIDI includes a limited number of MIKMIDICommand subclasses to support the most common MIDI message types. To support a new command type, you should create a new subclass of MIKMIDICommand (and please consider contributing it to the main MIKMIDI repository!). If you implement this subclass according to the rules explained below, it will automatically be used to represent incoming MIDI commands matching its MIDI command type.

To successfully subclass MIKMIDICommand, you must override at least the following methods:

• +supportedMIDICommandTypes: - Return an array of one or more MIKMIDICommandTypes that your subclass supports.
• +immutableCounterPartClass - Return the subclass itself (eg. return [MIKMIDINewTypeCommand class];)
• +mutableCounterPartClass - Return the mutable counterpart class (eg. return [MIKMIDIMutableNewTypeCommand class;])

Optionally, override -additionalCommandDescription to provide an additional, type-specific description string.

You must also implement +load and call [MIKMIDICommand registerSubclass:self] to register your subclass with the MIKMIDICommand machinery.

When creating a subclass of MIKMIDICommand, you should also create a mutable variant which is itself a subclass of your type-specific MIKMIDICommand subclass. The mutable subclass should override +isMutable and return YES.

If your subclass adds additional properties, beyond those supported by MIKMIDICommand itself, those properties should only be settable on instances of the mutable variant class. The preferred way to accomplish this is to implement the setters on the immutable, base subclass. In their implementations, check to see if self is mutable, and if not, raise an exception. Use the following line of code:

    if (![[self class] isMutable]) return MIKMIDI_RAISE_MUTATION_ATTEMPT_EXCEPTION;

For a straightforward example of a MIKMIDICommand subclass, see MIKMIDINoteOnCommand.

A MIDI channel pressure message. This message is most often sent by pressing down on the key after it “bottoms out”. This differs from a MIKMIDIPolyphonicKeyPressureCommand in that is the single greatest pressure of all currently depressed keys, hence the lack of a note property.

This is currently undocumented. Documentation contributions are always welcome!

A channel pressure (aftertouch) event.

This event is different from MIKMIDIPolyphonicKeyPressureEvent. This event is used to indicate the single greatest pressure value (of all the current depressed keys).

The mutable counter part of MIKMIDIChannelPressureEvent

MIKMIDIChannelVoiceCommand is used to represent MIDI messages whose type is any of the channel voice command subtypes. Specific support for channel voice command subtypes is provided by subclasses of MIKMIDIChannelVoiceCommand (e.g. MIKMIDIControlChangeCommand, MIKMIDINoteOnCommand, etc.)

The mutable counterpart of MIKMIDIChannelVoiceCommand.

MIKMIDIClientDestinationEndpoint represents a virtual endpoint created by your application to receive MIDI
from other applications on the system.

Instances of this class will be visible and can be connected to by other applications.

MIKMIDIClientSourceEndpoint represents a virtual endpoint created by your application to send MIDI
to other applications on the system.

Instances of this class will be visible and can be connected to by other applications.

MIKMIDIClock provides the number of seconds per MIDITimeStamp, as well as the number of MIDITimeStamps per a specified time interval.

Instances of MIKMIDIClock can be used to convert between MIDITimeStamp and MusicTimeStamp.

Mutable subclass of MIKMIDICommand. All MIKMIDICommand subclasses have mutable variants.

MIKMIDICommandThrottler is a simple utility class useful for throttling e.g. jog wheel/turntable controls, which otherwise send many messages per revolution.

MIKMIDIConnectionManager can be used to manage a set of connected devices. It can be configured to automatically connect to devices as they are added, and disconnect from them as they are removed. It also supports saving the list of connected to NSUserDefaults and restoring them upon relaunch.

The use of MIKMIDIConnectionManager is optional. It is meant to be useful in implementing functionality that many MIDI device enabled apps need. However, simple connection to devices or MIDI endpoints can be done with MIKMIDIDeviceManager directly, if desired.

A MIDI control change message.

The mutable counterpart of MIKMIDIControlChangeCommand.

Control change events are typically sent when a controller value changes. Controllers include devices such as pedals and levers.

This event is the counterpart to MIKMIDIControlChangeCommand in the context of sequences/MIDI Files.

The mutable counter part of MIKMIDIControlChangeEvent

MIKMIDIDestinationEndpoint represents a destination (output) MIDI endpoint. It is essentially an Objective-C wrapper for instances of CoreMIDI’s MIDIEndpoint class which are kMIDIObjectType_Destination type endpoints.

MIDI destination endpoints are contained by MIDI entities, which are in turn contained by MIDI devices. MIDI messages can be outputed through a destination endpoint using MIKMIDIDeviceManager’s -sendCommands:toEndpoint:error: method.

Note that MIKMIDIDestinationEndpoint does not declare any methods of its own. All its methods can be found on its superclasses: MIKMIDIEndpoint and MIKMIDIObject. Also, MIKMIDIDestinationEndpoint itself is only used to represent MIDI endpoints owned by external applications/devices. To create virtual destination endpoints to be owned by your application and offered to others, use its subclass, MIKMIDIClientDestinationEndpoint instead.

MIKMIDIDevice represents a MIDI device such as a DJ controller, MIDI piano keyboard, etc.

Overview

MIDI devices are for example, DJ controllers, MIDI piano keyboards, etc. For many applications, being able to discover, connect to, and receive messages from devices is fundamental to their use of MIDI. Instances of MIKMIDIDevice represent a MIDI device and MIKMIDIDevice includes methods for retrieving information about the device as well as obtaining its MIDI entities and endpoints in order to communicate with it.

MIDI devices can contain multiple entities, and each entity can contain multiple source and destination endpoints. Commonly, however, a device will contain only a single entity, which contains a single source endpoint, and a single destination endpoint.

Retrieving Available Devices

To retrieve a list of the devices that are available, use -[MIKMIDIDeviceManager availableDevices]. Note that some devices (e.g. some Native Instruments DJ controllers) have drivers that present them as pairs of virtual MIDI endpoints. These devices will not be available in the array returned by -availableDevices, and instead will be represented by virtual endpoints found in the arrays returned by -[MIKMIDIDeviceManager virtualSources] and -[MIKMIDIDeviceManager virtualDestinations]. MIKMIDIDevice can be used to “wrap” virtual sources so that it can be used with devices that present solely using virtual endpoings. See +deviceWithVirtualEndpoints: for more.

Connecting to a Device

To connect a device and start receiving MIDI messages from it, you must first get the source endpoints you want to connect to. Often there will be only one. You can retrieve all of a devices source endpoints using the following:

    NSArray *sources = [self.device.entities valueForKeyPath:@"@unionOfArrays.sources"];
  MIKMIDISourceEndpoint = [source firstObject]; // Or whichever source you want, but often there's only one.

Next, connect to that source using MIKMIDIDeviceManager:

MIKMIDIDeviceManager *manager = [MIKMIDIDeviceManager sharedDeviceManager];
NSError *error = nil;
BOOL success = [manager connectInput:source error:&error eventHandler:^(MIKMIDISourceEndpoint *source, NSArray *commands) {
    for (MIKMIDICommand *command in commands) {
        // Handle each command
    }
}];
if (!success) {
    NSLog(@"Unable to connect to %@: %@", source, error);
    // Handle the error
}

MIKMIDIDeviceManager is used to retrieve devices and virtual endpoints available on the system, as well as for connecting to and disconnecting from MIDI endpoints. It is a singleton object.

To get a list of devices available on the system, call -availableDevices. Virtual sources can be retrieved by calling -virtualSources and -virtualDevices, respectively. All three of these properties, are KVO compliant, meaning they can be observed using KVO for changes, and (on OS X) can be bound to UI elements using Cocoa bindings.

MIKMIDIDeviceManager is also used to connect to and disonnect from MIDI endpoints, as well as to send and receive MIDI messages. To connect to a MIDI source endpoint, call -connectInput:error:eventHandler:. To disconnect, call -disconnectInput:. To send MIDI messages/commands to an output endpoint, call -sendCommands:toEndpoint:error:.

Base class for MIDI endpoint objects. Not used directly, rather, in use, instances will always be instances of MIKMIDISourceEndpoint or MIKMIDIDestinationEndpoint.

MIKMIDIEndpointSynthesizer is a subclass of MIKMIDISynthesizer that provides a very simple way to synthesize MIDI commands coming from a MIDI endpoint (e.g. from a connected MIDI piano keyboard) to produce sound output.

To use it, simply create a synthesizer instance with the source you’d like it to play. It will continue playing incoming MIDI until it is deallocated.

MIKMIDIEntity represents a logical grouping of endpoints within a MIDI device. It essentially acts as a simple container for endpoints.

As part of MIKMIDIDevice’s support for wrapping virtual endpoints, an MIKMIDIEntity can also be created using virtual MIDI endpoints.

In MIKMIDI, MIDI events are objects. Specifically, they are instances of MIKMIDIEvent or one of its subclasses. MIKMIDIEvent’s subclasses each represent a specific type of MIDI event, for example, note events will be instances of MIKMIDINoteEvent. MIKMIDIEvent includes properties for getting information and data common to all MIDI events. Its subclasses implement additional method and properties specific to messages of their associated type.

MIKMIDIEvent is also available in mutable variants, most useful for creating events to be sent out by your application.

To create a new event, typically, you should use +midiEventWithTimeStamp:eventType:data:(NSData *)data

Subclass MIKMIDIEvent

Support for the various MIDI event types is provided by type-specific subclasses of MIKMIDIEvent. For example, note events are represented using MIKMIDINoteEvent.

To support a new event type, you should create a new subclass of MIKMIDIEvent (and please consider contributing it to the main MIKMIDI repository!). If you implement this subclass according to the rules explained below, it will automatically be used to represent MIDI events matching its MIDI event type.

To successfully subclass MIKMIDIEvent, you must override at least the following methods:

• +supportsMIKMIDIEventType: - Return YES when passed the MIKMIDIEventType value your subclass supports.
• +immutableCounterPartClass - Return the subclass itself (eg. return [MIKMIDINewTypeEvent class];)
• +mutableCounterPartClass - Return the mutable counterpart class (eg. return [MIKMIDIMutableNewTypeEvent class;])

Optionally, override -additionalEventDescription to provide an additional, type-specific description string.

You must also implement +load and call [MIKMIDIEvent registerSubclass:self] to register your subclass with the MIKMIDIEvent machinery.

When creating a subclass of MIKMIDIEvent, you should also create a mutable variant which is itself a subclass of your type-specific MIKMIDIEvent subclass. The mutable subclass should override +isMutable and return YES.

If your subclass adds additional properties, beyond those supported by MIKMIDIEvent itself, those properties should only be settable on instances of the mutable variant class. The preferred way to accomplish this is to implement the setters on the immutable, base subclass. In their implementations, check to see if self is mutable, and if not, raise an exception. Use the following line of code:

    if (![[self class] isMutable]) return MIKMIDI_RAISE_MUTATION_ATTEMPT_EXCEPTION;

For a straightforward example of a MIKMIDIEvent subclass, see MIKMIDINoteEvent.

Mutable subclass of MIKMIDIEvent. All MIKMIDIEvent subclasses have mutable variants.

MIKMIDIInputPort is an Objective-C wrapper for CoreMIDI’s MIDIPort class, and is only for source ports. It is not intended for use by clients/users of of MIKMIDI. Rather, it should be thought of as an MIKMIDI private class.

Overview

MIKMIDIMapping includes represents a complete mapping between a particular hardware controller, and an application’s functionality. Primarily, it acts as a container for MIKMIDIMappingItems, each of which specifies the mapping for a single hardware control.

MIKMIDIMapping can be stored on disk using a straightforward XML format, and includes methods to load and write these XML files. Currently this is only implemented on OS X (see https://github.com/mixedinkey-opensource/MIKMIDI/issues/2 ).

Another class, MIKMIDIMappingManager can be used to manage both application-supplied, and user customized mappings.

Creating Mappings

MIKMIDIMappings can be generated manually, as the XML format is fairly straightforward. MIKMIDI also includes powerful functionality to assist in creating a way for users to easily create their own mappings using a “MIDI learning” interface.

Using Mappings

MIKMIDI does not include built in support for automatically routing messages using a mapping, so a user of MIKMIDI must write some code to make this happen. Typically, this is done by having a single controller in the application be responsible for receiving all incoming MIDI messages. When a MIDI message is received, it can query the MIDI mapping for the mapping item correspoding to the incomding message, then send the command to the mapped responder. Example code for this scenario:

- (void)connectToMIDIDevice:(MIKMIDIDevice *)device {
    MIKMIDIDeviceManager *manager = [MIKMIDIDeviceManager sharedDeviceManager];
    BOOL success = [manager connectInput:source error:error eventHandler:^(MIKMIDISourceEndpoint *source, NSArray *commands) {
        for (MIKMIDICommand *command in commands) {
            [self routeIncomingMIDICommand:command];
        }
    }];

    if (success) self.device = device;
}

- (void)routeIncomingMIDICommand:
{
    MIKMIDIDevice *controller = self.device; // The connected MIKMIDIDevice instance
    MIKMIDIMapping *mapping = [[[MIKMIDIMappingManager sharedManager] mappingsForControllerName:controller.name] anyObject];
    MIKMIDIMappingItem *mappingItem = [[self.MIDIMapping mappingItemsForMIDICommand:command] anyObject];
    if (!mappingItem) return;

    id<MIKMIDIResponder> responder = [NSApp MIDIResponderWithIdentifier:mappingItem.MIDIResponderIdentifier];
    if ([responder respondsToMIDICommand:command]) {
        [responder handleMIDICommand:command];
    }
}

MIKMIDIMappingGenerator is used to map incoming commands from a MIDI device to MIDI responders in an application. It is intended to be used as the basis for a MIDI learning interface, where the application steps through controls/features and for each control, the user simply activates the hardware MIDI control (button, knob, etc.) to map it to that application function.

MIKMIDIMappingGenerator is able to interpret messages coming from a device to determine characteristics of the control sending the messages. This information is stored in the generated mapping for later use in correctly responding to incomding messages from each control. For example, some buttons on MIDI devices send a single message when pressed down, while other button send a message on press, and another on release. MIKMIDIMappingGenerator can determine the behavior for a button during mapping, so that an application knows to expect two messages from the mapped button during later use.

MIKMIDIMappingItem contains information about a mapping between a physical MIDI control, and a single command supported by a particular MIDI responder object.

MIKMIDIMappingItem specifies the command type, and MIDI channel for the commands sent by the mapped physical control along with the control’s interaction type (e.g. knob, turntable, button, etc.). It also specifies the (software) MIDI responder to which incoming commands from the mapped control should be routed.

MIKMIDIMappingManager provides a centralized way to manage an application’s MIDI mappings. It handles both bundled (built in) mapping files, as well as user-customized mappings. It will automatically load both bundled and user mappings from disk. It will also save user mappings to an appropriate location on disk, providing an easy to way to support the ability to import user mappings to an applicaation.

MIKMIDIMappingManager is a singleton.

A meta event containing copyright information.

The mutable counterpart of MIKMIDIMetaCopyrightEvent.

A meta event containing cue point information.

The mutable counterpart of MIKMIDIMetaCuePointEvent.

A MIDI meta event.

The mutable counterpart of MIKMIDIMetaEvent.

A meta event containing an instrument name.

The mutable counterpart of MIKMIDIMetaInstrumentNameEvent.

A meta event containing key signature information.

The mutable counterpart of MIKMIDIMetaKeySignatureEvent.

A meta event containing lyrics.

The mutable counterpart of MIKMIDIMetaLyricEvent.

A meta event containing marker information.

The mutable counterpart of MIKMIDIMetaMarkerTextEvent.

A meta event containing sequence information.

The mutable counterpart of MIKMIDIMetaSequenceEvent.

A meta event containing text.

The mutable counterpart of MIKMIDIMetaTextEvent.

A meta event containing time signature information.

The mutable counterpart of MIKMIDIMetaTimeSignatureEvent.

A meta event containing a track name.

The mutable counterpart of MIKMIDIMetaTrackSequenceNameEvent

This class is only a subclass of MIKMIDIEndpointSynthesizer so it continues to function with MIKMIDIPlayer while it still exists. Once MIKMIDIPlayer is removed from the code base, expect this to become a subclass of MIKMIDISynthesizer.

A MIDI note on message.

The mutable counterpart of MIKMIDINoteCommand.

A MIDI note event.

The mutable counterpart of MIKMIDINoteEvent

A MIDI note off message.

The mutable counterpart of MIKMIDINoteOffCommand.

A MIDI note on message.

The mutable counterpart of MIKMIDINoteOnCommand.

MIKMIDIObject is the base class for all of MIKMIDI’s Objective-C wrapper classes for CoreMIDI classes. It corresponds to MIDIObject in CoreMIDI.

MIKMIDIObject is essentially an “abstract” base class, although it does implement several methods common to all MIDI objects.

MIKMIDIOutputPort is an Objective-C wrapper for CoreMIDI’s MIDIPort class, and is only for destination ports. It is not intended for use by clients/users of of MIKMIDI. Rather, it should be thought of as an MIKMIDI private class.

A MIDI pitch bend change command.

On devices, pitch bends messages are usually generated using a wheel or lever.

This is currently undocumented. Documentation contributions are always welcome!

A pitch bed change event.

This event indicates a pitch bend change. On devices, pitch bends are usually generated using a wheel or lever.

The mutable counterpart of MIKMIDIPitchBendChangeEvent.

MIKMIDIPlayer can be used to play an MIKMIDISequence.

A MIDI polyphonic key pressure message. This message is most often sent by pressing down on the key after it “bottoms out”.

The mutable counterpart to MIKMIDIPolyphonicKeyPressureCommand.

A polyphonic key pressure (aftertouch) event.

This event most often represents pressing down on a key after it “bottoms out”.

The mutable counter part of MIKMIDIPolyphonicKeyPressureEvent

MIKMIDIPort is an Objective-C wrapper for CoreMIDI’s MIDIPort class. It is not intended for use by clients/users of of MIKMIDI. Rather, it should be thought of as an MIKMIDI private class.

A MIDI program change message.

Program change messages indicate a change in the patch number. These messages can be sent to to a MIDI device or synthesizer to change the instrument the instrument/voice being used to synthesize MIDI.

The mutable counterpart of MIKMIDIProgramChangeCommand

A MIDI program change event.

Program change events indicate a change in the patch number. These events can be sent to to a MIDI device or synthesizer to change the instrument the instrument/voice being used to synthesize MIDI.

This event is the counterpart to MIKMIDIProgramChangeCommand in the context of sequences/MIDI Files.

The mutable counter part of MIKMIDIProgramChangeEvent

Instances of MIKMIDISequence contain a collection of MIDI tracks. MIKMIDISequences may be thought of as MIDI “songs”. They can be loaded from and saved to MIDI files. They can also be played using an MIKMIDISequencer.

MIKMIDISequencer can be used to play and record to an MIKMIDISequence.

MIKMIDISourceEndpoint represents a source (input) MIDI endpoint. It is essentially an Objective-C wrapper for instances of CoreMIDI’s MIDIEndpoint class which are kMIDIObjectType_Source type endpoints.

MIDI source endpoints are contained by MIDI entities, which are in turn contained by MIDI devices. MIDI sources can be connected in order to receive data from them using MIKMIDIDeviceManager’s -connectInput:error:eventHandler:virtualDestinations method.

Note that MIKMIDISourceEndpoint does not declare any methods of its own. All its methods can be found on its superclasses: MIKMIDIEndpoint and MIKMIDIObject.

MIKMIDISynthesizer provides a simple way to synthesize MIDI messages to produce sound output.

To use it, simply create a synthesizer instance, then pass MIDI messages to it by calling -handleMIDIMessages:.

A subclass, MIKMIDIEndpointSynthesizer, adds the ability to easily connect to a MIDI endpoint and automatically synthesize incoming messages.

MIKMIDISynthesizerInstrument is used to represent

A MIDI System Exclusive (SysEx) message. System exclusive messages are messages defined by individual manufacturers of MIDI devices. They can contain arbitrary data and can be used to support commands and responses not explicitly supported by the standard portion of MIDI spec. There are also some “Universal Exclusive Mesages”, which while a type of SysEx message, are not manufacturer/device specific.

The mutable counter part of MIKMIDISystemExclusiveCommand.

A MIDI System Keep Alive message (aka Active Sensing). Keep alive messages are sent repeatedly to tell the receiver of them that the MIDI connection is alive and working. Not all devices will send these at all.

Per the MIDI spec, if a device does receive a keep alive message, it should expect to receive another no more than 300 ms later. If it does not, it can assume the connection has been terminated, and turn off all currently active voices/notes.

Note that MIKMIDI doesn’t (currently) implement this behavior at all, and it is up to MIKMIDI clients to implement it if so desired.

The mutable counter part of MIKMIDISystemKeepAliveCommand.

A MIDI system message command. This class is also the base class for subclasses representing specific system message subtypes (e.g. SysEx).

Mutable counterpart for MIKMIDISystemMessageCommand.

A MIDI tempo event.

The mutable counterpart of MIKMIDITempoEvent.

Instances of MIKMIDITrack contain sequences of MIDI events. Commonly, these will be MIDI notes. Multiple MIKMIDITracks can be contained in a MIKMIDISequence, which can be played.