#import <MKMidi.h>
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 |
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.
- (MKConductor *) conductor |
Returns the conductor that the MKNotes originating with MKMidi will return when sent the -conductor message.
- (id) setConductor: | (MKConductor *) | aConductor |
Sets the MKConductor that the MKNotes originating with MKMidi will return when sent the -conductor message.
aConductor | is an MKConductor. |
+ (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.>>
devName | is a NSString instance. | |
hostName | is a NSString instance. |
+ (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."
devName | is a NSString instance. |
+ (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.
- (id) initOnDevice: | (NSString *) | devName | ||
hostName: | (NSString *) | hostName | ||
Initialises an allocated instance for a named MIDI device on a named host.
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. |
- (id) initOnDevice: | (NSString *) | devName |
Initialises an allocated instance for a named MIDI device on the local host.
devName | An NSString naming the device. This should be that obtained from +getDriverNames. |
- (id) init |
Initialises an allocated instance on the default MIDI device on the local host.
Returns the receiver's MKDeviceStatus device status.
- (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.
- (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.
- (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.
- (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.
- (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.
- (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: | (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.
yesOrNo | is a BOOL. |
- (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.
- (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.
channel | is an unsigned MIDI channel. |
- (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.
channel | is an unsigned MIDI channel. |
- (MKNoteReceiver *) noteReceiver |
- (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.
- (MKNoteSender *) noteSender |
- (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.
- (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.
yesOrNo | is a BOOL. |
- (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.
- (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.
param | is a MKMidiParVal. |
- (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].
param | is a MKMidiParVal. |
- (double) localDeltaT |
Returns the receiver's local delta time in seconds.
- (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.
value | is a double. |
- (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.
yesOrNo | is a BOOL. |
- (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.
Unlike allNotesOff, this method sends MIDI noteOffs regardless of whether an unmatched MIDI noteOn was previously sent.
- (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.
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.
- (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.
format | is a short *. | |
h | is a short *. | |
m | is a short *. | |
s | is a short *. | |
f | is a short *. |
- (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.
+ (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:.
+ (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.
+ (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.
- (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.
- (NSMutableArray*) noteReceivers [protected] |
The object's collection of MKNoteSenders.
- (MKDeviceStatus) deviceStatus [protected] |
The object's collection of MKNoteReceivers.
- (NSString*) midiDevName [protected] |
See MKDeviceStatus.h
- (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