javax.microedition.media.control
Interface MIDIControl

All Superinterfaces:
Control

public interface MIDIControl
extends Control

MIDIControl provides access to MIDI rendering and transmitting devices.

Typical devices that are controlled with MIDIControl are internal synthesizers (software/hardware) or external hardware ports. Devices are virtual, i.e. even if there is only one physical synthesizer, all instances of MIDIControl seem to operate on its own synthesizer.

General functionality of this control is:

  1. Querying current state of the device:
  2. Querying the banks of the synthesizer:
  3. Set the volume assigned to each channel
  4. Set the bank/program assigned to a channel
  5. Send short MIDI messages to the device
  6. Send long MIDI messages (system exclusive)

In Java Sound terms, MIDIControl combines methods and concepts of the interfaces Transmitter, Receiver, Synthesizer, MidiChannel, Soundbank, and Patch.

In this context, the following naming conventions are used:

The conception of MIDIControl is based on scope and abstraction level:

A useful function is "Panic": immediately turn off all sounds and notes. It can be implemented using the following code fragment:

    int CONTROL_ALL_SOUND_OFF = 0x78;
    for (int channel = 0; channel < 16; channel++) {
         shortMidiEvent(CONTROL_CHANGE | channel, CONTROL_ALL_SOUND_OFF, 0);
    }
   

The implementation need not support the various query methods. This is a technical limitation, as the MIDI standard does not provide a standardized means to query the current program or the installed soundbanks. This especially applies to external MIDI ports. Optional methods must not be called if isBankQuerySupported() returns false.

Since:
JDE 4.0.0
See Also:
Player, RateControl, TempoControl, PitchControl

Field Summary
static int CONTROL_CHANGE
          Command value for Control Change message (0xB0, or 176).
static int NOTE_ON
          Command vlaue for Note On message (0x90, or 144).
 
Method Summary
 int[] getBankList(boolean custom)
          Returns list of installed banks.
 int getChannelVolume(int channel)
          Get volume for the given channel.
 String getKeyName(int bank, int prog, int key)
          Given bank, program and key, get name of key.
 int[] getProgram(int channel)
          Returns program assigned to channel.
 int[] getProgramList(int bank)
          Given bank, get list of program numbers.
 String getProgramName(int bank, int prog)
          Given bank and program, get name of program.
 boolean isBankQuerySupported()
          Returns whether banks of the synthesizer can be queried.
 int longMidiEvent(byte[] data, int offset, int length)
          Sends a long MIDI event to the device, typically a system exclusive message.
 void setChannelVolume(int channel, int volume)
          Set volume for the given channel.
 void setProgram(int channel, int bank, int program)
          Set program of a channel.
 void shortMidiEvent(int type, int data1, int data2)
          Sends a short MIDI event to the device.
 

Field Detail

CONTROL_CHANGE

public static final int CONTROL_CHANGE
Command value for Control Change message (0xB0, or 176).
See Also:
shortMidiEvent(int, int, int)
Since:
JDE 4.0.0

NOTE_ON

public static final int NOTE_ON
Command vlaue for Note On message (0x90, or 144). To turn a note off, send a NOTE_ON message with 0 velocity. Alternatively, a Note Off message (0x80) can be sent.
See Also:
shortMidiEvent(int, int, int)
Since:
JDE 4.0.0
Method Detail

getBankList

public int[] getBankList(boolean custom)
                  throws MediaException
Returns list of installed banks. If the custom parameter is true, a list of custom banks is returned. Otherwise, a list of all banks (custom and internal) is returned.

As there is no MIDI equivalent to this method, this method is optional, indicated by isBankQuerySupported(). If it returns false, this function is not supported and throws an exception.

Parameters:
custom - if set to true, returns a list of custom banks.
Returns:
an arrya of all installed bank numbers. Each bank number is in the range of 0..16383.
Throws:
MediaException - if this device does not support retrieval of banks
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0
See Also:
isBankQuerySupported()

getChannelVolume

public int getChannelVolume(int channel)
Get volume for the given channel. The return value is independent of the master volume, which is set and retrieved with VolumeControl.

As there is no MIDI equivalent to this method, the implementation may not always know the current volume for a given channel. In this case the return value is -1.

Parameters:
channel - 0-15
Returns:
channel volume, 0-127, or -1 if not known
Throws:
IllegalArgumentException - Thrown if channel is out of range.
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0
See Also:
setChannelVolume(int, int)

getKeyName

public String getKeyName(int bank,
                         int prog,
                         int key)
                  throws MediaException
Given bank, program and key, get name of key. This method applies to key-mapped banks (i.e. percussive banks or effect banks) only. A return value of null means that the specified key is not mapped to a sound. For melodic banks, where each key (=note) produces the same sound at a different pitch, this method always returns null. For space-saving reasons, an implementation may return an empty string instead of the key name. To find out whicih keys in a specific program are mapped to a sound, iterate through all keys (0-127) and comare the return value of getKeyName to non-null.

As there is no MIDI equivalent to this method, this method is optional, indicated by isBankQuerySupported(). If it returns false, this function is not supported and throws an exception.

Parameters:
bank - 0-16383
prog - 0-127
key - 0-127
Returns:
name of the specified key, empty string, or null if the key is not mapped to a sound.
Throws:
IllegalArgumentException - Thrown if bank, prog or key is out of range.
MediaException - Thrown if the bank or program is not installed (internal or custom), or if this device does not support retrieval or key names
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0
See Also:
isBankQuerySupported()

getProgram

public int[] getProgram(int channel)
                 throws MediaException
Returns program assigned to channel. It represents the current state of the channel. During playback of a MIDI file, the program may change due to program change events in the MIDI file.

To set a program for a channel, use setProgram(int, int, int).

The returned array is represented by an array {bank,program}.

If the device has not been initialized with a MIDI file, or the MIDI file does not contain a program change for this channel, an implementation specific default value is returned.

As there is no MIDI equivalent to this method, this method is optional, indicated by isBankQuerySupported(). If it returns false, this function is not supported and throws an exception.

Parameters:
channel - 0-15
Returns:
program assigned to channel, represented by array {bank,program}.
Throws:
IllegalArgumentException - Thrown if channel is out of range.
IllegalStateException - Thrown if the player has not been prefetched.
MediaException - Thrown if querying of banks is not supported.
Since:
JDE 4.0.0
See Also:
isBankQuerySupported(), setProgram(int, int, int)

getProgramList

public int[] getProgramList(int bank)
                     throws MediaException
Given bank, get list of program numbers. If an only if this bank is not installed, an empty array is returned.

As there is no MIDI equivalent to this method, this method is optional, indicated by isBankQuerySupported(). If it returns false, this function is not supported and throws an exception.

Parameters:
bank - 0..16383
Returns:
an array of programs defined in the given bank. Each program number is from 0..127.
Throws:
IllegalArgumentException - Thrown if bank is out of range.
MediaException - Thrown if the device does not suppoort retrieval of programs.
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0
See Also:
setProgram(int, int, int), isBankQuerySupported()

getProgramName

public String getProgramName(int bank,
                             int prog)
                      throws MediaException
Given bank and program, get name of program. For space-saving reasons, an implementation may return an empty string.

As there is no MIDI equivalent to this method, this method is optional, indicated by isBankQuerySupported(). If it returns false, this function is not supported and throws an exception.

Parameters:
bank - 0-16383
prog - 0-127
Returns:
name of the specified program, or empty string.
Throws:
IllegalArugmentException - Thrown if bank or prog is out of range.
MediaException - Thrown if the bank or program is not installed (internal or custom), or if this device does not support retrieval of program names
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0
See Also:
isBankQuerySupported()

isBankQuerySupported

public boolean isBankQuerySupported()
Returns whether banks of the synthesizer can be queried.

If this function returns true, then the following methods can be used to query banks:

Returns:
true if this device supports querying of banks
Since:
JDE 4.0.0

longMidiEvent

public int longMidiEvent(byte[] data,
                         int offset,
                         int length)
Sends a long MIDI event to the device, typically a system exclusive message. This method passes the data directly to the receiving device. The data array's contents are not checked for validity.

It is possible to send short events, or even a series of short events with this method.

Parameters:
data - array of the bytes to send
offset - start offset in data array
length - number of bytes to be sent
Returns:
the number of bytes actually sent to the device or -1 if an error occured
Throws:
IllegalArgumentException - Thrown if any of the given parameters is not valid.
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0

setChannelVolume

public void setChannelVolume(int channel,
                             int volume)
Set volume for the given channel. To mute, set to 0. This sets the current volume for the channel and may be overwritten during playback events in a MIDI sequence.

It is a high-level convenience function. Internally, the following command is executed:

    shortMidiEvent( (CONTROL_CHANGE | channel), CONTROL_MAIN_VOLUME, 0);
 
where this constant is used:
    int CONTROL_MAIN_VOLUME = 0x07
 

The channel volume is independent of the master volume, which is accessed with VolumeControl. Setting the channel volume does not modify the value of the master volume -- and vice versa: changing the value of the master volume does not change any channel's volume value. The synthesizer mixes the output of up to 16 channels, each channel with its own channel volume. The master volume then controls the volume of the mix. Consequently, the effective output volume of a channel is the product of master volume and channel volume.

Setting the channel volume does not generate a VOLUME_CHANGED event.

Parameters:
channel - 0-15
volume - 0-127
Throws:
IllegalArugmentException - Thrown if channel or volume is out of range.
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0
See Also:
getChannelVolume(int)

setProgram

public void setProgram(int channel,
                       int bank,
                       int program)
Set program of a channel. This sets the current program for the channel and may be overwritten during playback by events in a MIDI sequence.

It is a high level convenience function. Internally, these method calls are executed:

    shortMidiEvent( (CONTROL_CHANGE | channel), CONTROL_BANK_CHANGE_MSB, (bank >> 7) );
    shortMidiEvent( (CONTROL_CHANGE | channel), CONTROL_BANK_CHANGE_LSB, (bank & 0x7F) );
    shortMidiEvent( (PROGRAM_CHANGE | channel), program, 0 );
 

In order to use the default bank (the initial bank), set the bank parameters to -1.

In order to se a program without explicitly setting the bank, use the following call:

    shortMidiEvent( (PROGRAM_CHANGE | channel), program, 0 );
 

In both examples, the following constants are used:

    int PROGRAM_CHANGE = 0xC0;
    int CONTROL_BANK_CHANGE_MSB = 0x00;
    int CONTROL_BANK_CHANGE_LSB = 0x20;
 
Parameters:
channel - 0-15
bank - 0-16383, or -1 for default bank.
program - 0-127
Throws:
IllegalArugmentException - Thrown if any of the given parameters is out of range.
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0
See Also:
getProgram(int)

shortMidiEvent

public void shortMidiEvent(int type,
                           int data1,
                           int data2)
Sends a short MIDI event to the device. Short MIDI events consist of 1, 2, or 3 unsigned bytes. For non-realtime events, the first byte is split up into status (upper nibble, 0x80-0xF0) and channel (0x00-0xF0). For example to send a Note On event on a given channel, use this line:
    shortMidiEvent( (NOTE_ON | channel), note, velocity );
 

For events with less than 3 bytes, set the remaining data bytes to 0.

There is no guarantee that a specific implementation of a MIDI device supports all event types. Also, the MIDI protocol does not implement flow control and it is not guaranteed that an event reaches the destination. In both these cases, this method fails silently.

Static error checking is performed on the passed parameters. They have to specify a valid, complete MIDI event. Events with type < 0x80 are not valid MIDI events (-> running status). When an invalid event is encountered, an IllegalArugmentException is thrown.

Parameters:
type - 0x80..0xFF, excluding 0xF0 and 0xF7, which are reserved for system exclusive
data1 - for 2 and 3-byte events: first data byte, 0..127
data2 - for 3-byte events: second data byte, 0..127
Throws:
IllegalArgumentException - Thrown if one of the parameters is out of range.
IllegalStateException - Thrown if the player has not been prefetched.
Since:
JDE 4.0.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.