MKMidi Class Reference

A MKMidi object lets you communicate with a MIDI synthesizer by providing a simple interface to the MIDI device driver. More...

#import <MKMidi.h>

List of all members.

Public Member Functions

(MKConductor *) - conductor
 Returns the conductor that the MKNotes originating with MKMidi will return when sent the -conductor message.
(id) - setConductor:
 Sets the MKConductor that the MKNotes originating with MKMidi will return when sent the -conductor message.
(id) - initOnDevice:hostName:
 Initialises an allocated instance for a named MIDI device on a named host.
(id) - initOnDevice:
 Initialises an allocated instance for a named MIDI device on the local host.
(id) - init
 Initialises an allocated instance on the default MIDI device on the local host.
(void) - dealloc
 free object, closing device if it is not already closed.
(MKDeviceStatus- deviceStatus
 Returns the receiver's MKDeviceStatus device status.
(id) - open
 Opens the receiver, thus enabling two-way communication with the MIDI device it represents.
(id) - openInputOnly
 Opens the receiver for input from the MIDI device it represents.
(id) - openOutputOnly
 Opens the receiver for output to the MIDI device it represents.
(id) - run
 Starts the receiver's clock, first opening the receiver if necessary, and sets the receiver's status to MK_devRunning.
(id) - stop
 Stops the receiver's clock and sets the receiver's status to MK_devStopped; opens the receiver if it isn't already open.
(void) - close
 Waits for the receiver's output queue to empty and then closes the receiver, sets its status to MK_devClosed, and releases the device port.
(id) - abort
 Immediately closes the receiver without waiting for the output queue to empty, sets its status to MK_devClosed, and releases the device port.
(id) - setOutputTimed:
 Establishes whether MIDI messages are sent timed or untimed, as yesOrNo is YES or NO.
(BOOL) - outputIsTimed
 Returns YES if the receiver is timed, otherwise returns NO.
(MKNoteSender *) - channelNoteSender:
 Returns the MKNoteSender corresponding to channel n, or nil if none.
(MKNoteReceiver *) - channelNoteReceiver:
 Returns the MKNoteReceiver corresponding to the specified channel n, or nil if none.
(MKNoteReceiver *) - noteReceiver
 Returns the default MKNoteReceiver.
(NSArray *) - noteReceivers
 Returns a NSArray containing the receiver's MKNoteReceivers.
(MKNoteSender *) - noteSender
 Returns the default MKNoteSender.
(NSArray *) - noteSenders
 Returns a NSArray containing the receiver's MKNoteSenders.
(id) - setUseInputTimeStamps:
 If yesOrNo is YES the MKConductor's clock is synched to the MIDI driver's clock whenever the receiver receives a MIDI message.
(BOOL) - useInputTimeStamps
 Returns YES if the MKConductor's clock is synched to the MIDI driver's clock, otherwise returns NO.
(id) - ignoreSys:
 Instructs the receiver to ignore messages that set the MK_sysRealTime parameter to param.
(id) - acceptSys:
 Instructs the receiver to accept in-coming MIDI messages that set the MK_sysRealTime parameter to the value specified in param, which must be one of the following:.
(double) - localDeltaT
 Returns the receiver's local delta time in seconds.
(id) - setLocalDeltaT:
 Sets the value of the receiver's local delta time, in seconds.
(id) - setMergeInput:
 If set to YES, the MKNotes fashioned from the incoming MIDI stream are all sent to MKNoteSender 0 (the one that normally gets only system messages).
(id) - awaitQueueDrain
 If the receiver is running, blocks until all enqueued MIDI data has been sent to the MIDI cable.
(id) - allNotesOffBlast
 If the receiver is open for output, sends a MIDI noteOff to the MIDI cable on every key number on every MIDI channel.
(id) - allNotesOff
 If the receiver is open for output, sends a MIDI noteOff to the MIDI cable for every key number and MIDI channel for which an unmatched MIDI noteOn was previously sent.
(double) - time
 Returns time according to the MIDI driver.
(id) - getMTCFormat:hours:min:sec:frames:
 This only works if the receiver is currently providing MIDI time code to a MKConductor.
(id) - synchConductor
 If the receiver has been set to provide MIDI time code to a MKConductor, this method returns that MKConductor. Otherwise, it returns nil.
(NSString *) - driverName
 Returns the name of the MIDI driver associated with this instance of MKMidi.
(NSString *) - description
 Returns description of which device, the unit and the host the MKMidi object has been initialised on.
(void) - downloadDLS:
 Download MMA DownLoadable Sounds with patch numbers provided.

Static Public Member Functions

(id) + midiOnDevice:host:
 If a MKMidi object for the device devName on host hostName doesn't already exist, this creates such an object and creates and adds to it a full complement of MKNoteSenders and MKNoteReceivers.
(id) + midiOnDevice:
 If a MKMidi object for the device devName doesn't already exist, this creates such an object and creates and adds to it a full complement of MKNoteSenders and MKNoteReceivers.
(id) + midi
 If a MKMidi object for the device “midi0“ doesn't already exist, this creates such an object and creates and adds to it a full complement of MKNoteSenders and MKNoteReceivers.
(NSArray *) + getDriverNames
 Returns an array of all available bidirectional driver names added to the system.
(NSArray *) + getDriverNamesForInput
 Returns an array of all available driver names for input.
(NSArray *) + getDriverNamesForOutput
 Returns an array of all available driver names for output.

Protected Attributes

NSMutableArray * noteReceivers
MKDeviceStatus deviceStatus
NSString * midiDevName
BOOL useInputTimeStamps
BOOL outputIsTimed
double localDeltaT


Detailed Description

A MKMidi object lets you communicate with a MIDI synthesizer by providing a simple interface to the MIDI device driver.

The MKMidi class also provides a mechanism that automatically converts MIDI messages into MKNote objects and vice versa, allowing you to incorporate MIDI data into a MusicKit application with a minimum of effort.

While inheriting neither from MKPerformer nor MKInstrument, the MKMidi class emulates both of them: Like a MKPerformer, it contains a NSArray of MKNoteSenders, and, like an MKInstrument, it contains a NSArray of MKNoteReceivers. A newly created MKMidi object contains 17 MKNoteSenders and 17 MKNoteReceivers, one for each of the 16 Voice Channels and one for the Basic Channel. (Note, however, that the method setMergeInput: allows the option of all messages to be sent via MKNoteSender 0. Similarly, if a MKNote is sent to MKNoteReceiver 0, the MK_midiChan parameter of that MKNote determines on which MIDI channel it is sent.)

Before a MKMidi object can receive messages from or send messages to an external synthesizer, it must be sent the open and run messages:

Balancing these two methods are stop and close:

The state of a MKMidi object with respect to the foregoing methods is described in its deviceStatus instance variable:

(Note that these are the same methods and MKDeviceStatus values used to control and describe the status of an MKOrchestra object.)

The MIDI driver has its own clock that's generally more regular and steadfast than the MKConductor's clock. To take advantage of this, the MKConductor is, by default, synched to incoming MIDI messages: When a MIDI message arrives, the MKConductor's clock is set to the time stated in the message timestamp. You can disable this feature by sending setUseInputTimeStamps: NO to a MKMidi object.

On the other side, as a MKMidi object initiates an outgoing MIDI message, it gives the message a timestamp that indicates when the message should be performed by the external MIDI device. By default, the MIDI driver looks at the timestamp and waits until the appropriate time (as determined by its own clock) to send the message on to the synthesizer. By sending setOutputTimed: NO to a MKMidi object, you can specify that the driver is to ignore the timestamps and send all messages as soon as it receives them.

Note that in all cases the MKConductor that's overseeing the MusicKit performance must be clocked if you want to use a MKMidi object.

As MKMidi receives MIDI messages it creates MKNote objects following these rules:

In sending messages to an external synthesizer, MKMidi converts MKNote objects to MIDI messages:

A number of parameters are provided to accommodate MIDI messages. These are described in the section titled Representation of MIDI in the MusicKit .

A MKMidi object can be used to synchronize a performance to incoming MIDI time code. To do so, send a MKConductor the message setMTCSynch:, with a MKMidi object as the argument. For further information on MIDI time code, see the appendix titled MIDI Time Code in the MusicKit .

The MIDI synthesizer is attached to a serial port at the back of a NeXT computer, to a MPU-401 compatible card installed in a P.C., to a MIDI device defined within Microsoft Windows DirectMusic or to a MIDI device defined within Apple MacOS X CoreMIDI.

See Administration/MidiHardwareInfo.rtf for using MIDI on NeXT hardware.


Member Function Documentation

- (MKConductor *) conductor  

Returns the conductor that the MKNotes originating with MKMidi will return when sent the -conductor message.

Returns:
By default, returns the defaultConductor, if the MKConductor class is loaded, else nil.

- (id) setConductor: (MKConductor *)  aConductor  

Sets the MKConductor that the MKNotes originating with MKMidi will return when sent the -conductor message.

Parameters:
aConductor is an MKConductor.
Returns:
Returns an id.

+ (id) midiOnDevice: (NSString *)  devName
host: (NSString *)  hostName 

If a MKMidi object for the device devName on host hostName doesn't already exist, this creates such an object and creates and adds to it a full complement of MKNoteSenders and MKNoteReceivers.

Otherwise, returns the existing object. This enables an application to access another machine's MIDI ports.

<<On Non-NeXT hardware, hostName is currently ignored - thus, you may not open a MIDI device on a network-based device when running on white hardware.>>

Parameters:
devName is a NSString instance.
hostName is a NSString instance.
Returns:
Returns an id.

+ (id) midiOnDevice: (NSString *)  devName  

If a MKMidi object for the device devName doesn't already exist, this creates such an object and creates and adds to it a full complement of MKNoteSenders and MKNoteReceivers.

Otherwise, returns the existing object. devName, for the NeXT (black) hardware, is "midi0" for serial port A or "midi1" for serial port B. On white hardware "midi0" corresponds to the value of the defaults data base variable MIDI0, owned by MIDI. (See the NeXT documentation on dwrite for more information about the defaults data base.) Alternatively, devName may be the direct driverName/unit combination, e.g. "Mididriver2."

Parameters:
devName is a NSString instance.
Returns:
Returns an id.

+ (id) midi  

If a MKMidi object for the device “midi0“ doesn't already exist, this creates such an object and creates and adds to it a full complement of MKNoteSenders and MKNoteReceivers.

Otherwise, returns the existing object. “midi0” corresponds to serial port A on the NeXT (black) hardware, the default MIDI port on other platforms.

Returns:
Returns an id.

- (id) initOnDevice: (NSString *)  devName
hostName: (NSString *)  hostName 

Initialises an allocated instance for a named MIDI device on a named host.

Parameters:
devName An NSString naming the device. This should be that obtained from +getDriverNames.
hostName An NSString naming the host machine that is running the MIDI device. Currently unused.
Returns:
Returns an initialised instance.

- (id) initOnDevice: (NSString *)  devName  

Initialises an allocated instance for a named MIDI device on the local host.

Parameters:
devName An NSString naming the device. This should be that obtained from +getDriverNames.
Returns:
Returns an initialised instance.

- (id) init  

Initialises an allocated instance on the default MIDI device on the local host.

Returns:
Returns an initialised instance.

Returns the receiver's MKDeviceStatus device status.

Returns:
Returns a MKDeviceStatus.

- (id) open  

Opens the receiver, thus enabling two-way communication with the MIDI device it represents.

The receiver's status is set to MK_devOpen. If the receiver is already open, its input and output message queues are flushed. Returns the receiver, or nil if it couldn't be opened.

Returns:
Returns an id.

- (id) openInputOnly  

Opens the receiver for input from the MIDI device it represents.

If the receiver is already open, its input message queue is flushed. Returns the receiver, or nil if it couldn't be opened.

Returns:
Returns an id.

- (id) openOutputOnly  

Opens the receiver for output to the MIDI device it represents.

If the receiver is already open, its output message queue is flushed. Returns the receiver, or nil if it couldn't be opened.

Returns:
Returns an id.

- (id) run  

Starts the receiver's clock, first opening the receiver if necessary, and sets the receiver's status to MK_devRunning.

Returns the receiver, or nil if it's closed and can't be opened.

Returns:
Returns an id.

- (id) stop  

Stops the receiver's clock and sets the receiver's status to MK_devStopped; opens the receiver if it isn't already open.

Returns the receiver, or nil if it's closed and can't be opened.

Returns:
Returns an id.

- (id) abort  

Immediately closes the receiver without waiting for the output queue to empty, sets its status to MK_devClosed, and releases the device port.

Returns:
Returns the receiver.

- (id) setOutputTimed: (BOOL)  yesOrNo  

Establishes whether MIDI messages are sent timed or untimed, as yesOrNo is YES or NO.

If the receiver is timed, messages are stamped with the MKConductor's notion of the current time (plus the global and local delta times). If it's untimed, the timestamps are always 0, indicating, to the MIDI driver, that the messages should be sent immediately. The default is timed.

Parameters:
yesOrNo is a BOOL.
Returns:
Returns an id.

- (BOOL) outputIsTimed  

Returns YES if the receiver is timed, otherwise returns NO.

The default is YES.

If setOutputTimed:YES is sent, events are sent to the driver with time stamps equal to the MKConductor's time plus "deltaT". (See MKSetDeltaT()). If setOutputTimed:NO is sent, events are sent to the driver with a time stamp of 0, indicating they are to be played as soon as they are received.

Returns:
Returns a BOOL.
See also:
-- setOutputTimed:

- (MKNoteSender *) channelNoteSender: (unsigned)  channel  

Returns the MKNoteSender corresponding to channel n, or nil if none.

A MKMidi object's MKNoteSenders are numbered such that 0 is the MKNoteSender that processes system/channel mode messages and 1 through 16 are the MKNoteSenders for the MIDI channels. The MKNoteSender corresponding to 0 is special. It uses the MK_midiChan parameter of the note, if any, to determine which midi channel to send the note on. If no MK_midiChan parameter is present, the default is channel 1. This MKNoteReceiver is also commonly used for MIDI channel mode and system messages.

Parameters:
channel is an unsigned MIDI channel.
Returns:
Returns an MKNoteSender instance.

- (MKNoteReceiver *) channelNoteReceiver: (unsigned)  channel  

Returns the MKNoteReceiver corresponding to the specified channel n, or nil if none.

A MKMidi object's MKNoteReceivers are numbered such that 0 is the MKNoteReceiver that processes system/channel mode messages and 1 through 16 are the MKNoteReceivers for the MIDI channels. The MKNoteReceiver corresponding to 0 is special. It uses the MK_midiChan parameter of the note, if any, to determine which MIDI channel to send the note on. If no MK_midiChan parameter is present, the default is channel 1.

Parameters:
channel is an unsigned MIDI channel.
Returns:
Returns an MKNoteReceiver instance.

- (MKNoteReceiver *) noteReceiver  

Returns the default MKNoteReceiver.

Returns:
Returns an MKNoteReceiver instance.

- (NSArray *) noteReceivers  

Returns a NSArray containing the receiver's MKNoteReceivers.

The NSArray object will be autoreleased, although its contents (the MKNoteReceiver objects themselves) will not be released.

Returns:
Returns an id.

- (MKNoteSender *) noteSender  

Returns the default MKNoteSender.

Returns:
Returns an id.

- (NSArray *) noteSenders  

Returns a NSArray containing the receiver's MKNoteSenders.

The NSArray object will be autoreleased, although its contents (the MKNoteSender objects themselves) will not be released.

Returns:
Returns an id.

- (id) setUseInputTimeStamps: (BOOL)  yesOrNo  

If yesOrNo is YES the MKConductor's clock is synched to the MIDI driver's clock whenever the receiver receives a MIDI message.

If the receiver isn't closed, this does nothing and returns nil; otherwise returns the receiver.

Parameters:
yesOrNo is a BOOL.
Returns:
Returns an id.

- (BOOL) useInputTimeStamps  

Returns YES if the MKConductor's clock is synched to the MIDI driver's clock, otherwise returns NO.

The default is YES.

By default, MKConductor's time is adjusted to that of the MKMidi input clock (useInputTimeStamps == YES). This is desirable when recording the MKNotes (e.g. with a MKPartRecorder). However, for real-time MIDI processing, it is preferable to use the MKConductor's time (useInputTimeStamps == NO). setUseInputTimeStamps: and useInputTimeStamps set and get, respectively, this flag.

Note that even with setUseInputTimeStamps:YES, the MKConductor's clock is not slave to the MIDI input clock. Rather, fine adjustment of the MKConductor's clock is made to match that of MIDI input. (Future releases of the MusicKit may provide the ability to use the MIDI clock as the primary source of time.)

It is the application's responsibility to insure that MKMidi is stopped when the performance is paused and that Midi is run when the performance is resumed.

Returns:
Returns a BOOL.

- (id) ignoreSys: (MKMidiParVal)  param  

Instructs the receiver to ignore messages that set the MK_sysRealTime parameter to param.

The list of values that are ignored by default is given in acceptSys:. Returns the receiver.

Parameters:
param is a MKMidiParVal.
Returns:
Returns an id.

- (id) acceptSys: (MKMidiParVal)  param  

Instructs the receiver to accept in-coming MIDI messages that set the MK_sysRealTime parameter to the value specified in param, which must be one of the following:.

MK_sysClock MK_sysStart MK_sysContinue MK_sysStop MK_sysActiveSensing.

By default, MIDI messages that set the MK_sysRealTime parameter are ignored.

These are currently the only MIDI messges that can be ignored. You enable or disable this feature using the ignoreSys: and acceptSys: methods. For example, to receive MK_sysActiveSensing, send [aMidiObj acceptSys: MK_activeSensing].

Parameters:
param is a MKMidiParVal.
Returns:
Returns the receiver.

- (double) localDeltaT  

Returns the receiver's local delta time in seconds.

Returns:
Returns a double.

- (id) setLocalDeltaT: (double)  value  

Sets the value of the receiver's local delta time, in seconds.

This has no effect if the receiver isn't timed. LocalDeltaT is added to time stamps sent to MIDI-out. This is in addition to the deltaT set with MKSetDeltaT(). Has no effect if the receiver is not in outputIsTimed mode. The default local delta time is 0.0.

Parameters:
value is a double.
Returns:
Returns an the receiver (an id).

- (id) setMergeInput: (BOOL)  yesOrNo  

If set to YES, the MKNotes fashioned from the incoming MIDI stream are all sent to MKNoteSender 0 (the one that normally gets only system messages).

In addition, a MK_midiChan is added so that the stream can be split up again later.

Parameters:
yesOrNo is a BOOL.
Returns:
Returns an id.

- (id) awaitQueueDrain  

If the receiver is running, blocks until all enqueued MIDI data has been sent to the MIDI cable.

Returns:
Returns an id.

- (id) allNotesOffBlast  

If the receiver is open for output, sends a MIDI noteOff to the MIDI cable on every key number on every MIDI channel.

Unlike allNotesOff, this method sends MIDI noteOffs regardless of whether an unmatched MIDI noteOn was previously sent.

Returns:
Returns an id.

- (id) allNotesOff  

If the receiver is open for output, sends a MIDI noteOff to the MIDI cable for every key number and MIDI channel for which an unmatched MIDI noteOn was previously sent.

Returns:
Returns an id.

- (double) time  

Returns time according to the MIDI driver.

If the deltaT mode is MK_DELTAT_SCHEDULER_ADVANCE, deltaT is added to this time. If the receiver is providing time code for a MKConductor, that MKConductor's timeOffset is reflected in the time returned by this method. Unlike most of the MusicKit time methods and functions, this one gets the current time, whether or not [MKConductor adjustTime] or [MKConductor lockPerformacne] was invoked.

See also:
MKSetDeltaTMode(), MKSetDeltaT() and MKConductor.
Returns:
Returns a double.

- (id) getMTCFormat: (short *)  format
hours: (short *)  h
min: (short *)  m
sec: (short *)  s
frames: (short *)  f 

This only works if the receiver is currently providing MIDI time code to a MKConductor.

Returns the current time from the MIDI driver. Unlike most of the MusicKit time methods and functions, this one gets the current time, whether or not [MKConductor adjustTime] or [MKConductor lockPerformacne] was invoked. If the deltaT mode is MK_DELTAT_SCHEDULER_ADVANCE, the returned value has deltaT added to it.

Parameters:
format is a short *.
h is a short *.
m is a short *.
s is a short *.
f is a short *.
Returns:
Returns an id.

- (id) synchConductor  

If the receiver has been set to provide MIDI time code to a MKConductor, this method returns that MKConductor. Otherwise, it returns nil.

Returns:
Returns an MKConductor instance.

+ (NSArray *) getDriverNames  

Returns an array of all available bidirectional driver names added to the system.

The arrays and strings are copied and autoreleased. Only those drivers which support both output and input are returned. To return additional drivers which may support only input or output, use +getDriverNamesForInput:.

Returns:
Returns an NSArray instance.

+ (NSArray *) getDriverNamesForInput  

Returns an array of all available driver names for input.

This list may include drivers that are also available for output and those drivers which are for input only.

Returns:
Returns an NSArray instance.

+ (NSArray *) getDriverNamesForOutput  

Returns an array of all available driver names for output.

This list may include drivers that are also available for input and those drivers which are for output only.

Returns:
Returns an NSArray instance.

- (NSString *) driverName  

Returns the name of the MIDI driver associated with this instance of MKMidi.

Returns:
Returns an NSString instance.

- (NSString *) description  

Returns description of which device, the unit and the host the MKMidi object has been initialised on.

Returns:
Returns an NSString instance.


Member Data Documentation

- (NSMutableArray*) noteReceivers [protected]

The object's collection of MKNoteSenders.

- (MKDeviceStatus) deviceStatus [protected]

The object's collection of MKNoteReceivers.

- (NSString*) midiDevName [protected]

- (BOOL) useInputTimeStamps [protected]

Midi device port name.

- (BOOL) outputIsTimed [protected]

YES if MKConductor's time updated from driver's time stamps.

- (double) localDeltaT [protected]

YES if the driver's clock is used for output


The documentation for this class was generated from the following file:

Generated on Sat Dec 5 17:01:15 2009 for MusicKit by  doxygen 1.5.6