| javax.microedition.media.control.MIDIControl
All known Subclasses: com.sun.mmedia.DirectMIDIControl,
| MIDIControl | | public interface MIDIControl extends javax.microedition.media.Control(Code) | | 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:
- Querying current state of the device:
- The programs that are currently assigned to each of the 16 channels
- Volume of each channel
- Querying the banks of the synthesizer:
- Get a list of internal sound banks
- Get a list of custom sound banks
- Get the list of programs of a sound bank
- Get the name of a specific program
- Set the volume assigned to a channel
- Set the bank/program assigned to a channel
- Send short MIDI messages to the device
- 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:
- A program refers to a single instrument. This is
also known as a patch.
- A bank is short for sound bank. It contains up
to 128 programs, numbered in the range from 0..127.
- An internal bank is provided by the software
implementation or the hardware of the device.
- A custom bank is installed by an application,
e.g. by loading an XMF meta file with an embedded bank.
The conception of MIDIControl is based on scope and
abstraction level:
MIDIControl has methods that are specific
to the device or renderer, and do not directly relate to a specific
MIDI file or sequence to be played. However, as devices are virtual,
MIDIControl's methods only operate on this virtual device.
On the other hand, it is also
possible to get an instance of MIDIControl
without providing a sequence or MIDI file; this is done by
specifying a magic Locator:
try{
Player
p = Manager.createPlayer(Manager.MIDI_DEVICE_LOCATOR);
MIDIControl
synth = (MIDIControl)p.getControls("javax.microedition.media.control.MIDIControl");
} catch (MediaException e) {
}
MIDIControl's methods can be considered
advanced, low level functionality. This has 2 implications:
MIDIControl is optional, i.e. no Player
instance is required to provide an implementation of
it- Basic media or MIDI player applications will not need
MIDIControl;
VolumeControl VolumeControl ,
TempoControl TempoControl , and
PitchControl PitchControl are sufficient for basic needs.
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
MIDIControl.isBankQuerySupported isBankQuerySupported returns false.
See Also: javax.microedition.media.Player
See Also: javax.microedition.media.control.RateControl
See Also: javax.microedition.media.control.TempoControl
See Also: javax.microedition.media.control.PitchControl |
| Field Summary | |
| int | CONTROL_CHANGE
Command value for Control Change message (0xB0, or 176). | | int | NOTE_ON
Command value for Note On message (0x90, or 144). |
| Method Summary | |
| int[] | getBankList(boolean custom)
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
MIDIControl.isBankQuerySupported isBankQuerySupported .
If it returns false, this function is not supported and throws an exception.
Parameters:
custom - if set to true, returns list of custom 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.
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
MIDIControl.isBankQuerySupported isBankQuerySupported .
If it returns false, this function is not supported and throws an exception.
Parameters:
bank - 0-16383
Parameters:
prog - 0-127
exception:
IllegalArgumentException - Thrown if bank or prog is out of range.
exception:
MediaException - Thrown if the bank or program is not installed (internal or custom), or if this device does not support retrieval of program names
exception:
IllegalStateException - Thrown if the player has not been prefetched. | | 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.
This method passes the data directly to the receiving device. | | 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.
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-0x0F).
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. |
| NOTE_ON | | int NOTE_ON(Code) | | Command value 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: MIDIControl.shortMidiEvent(int,int,int) |
| getBankList | | int[] getBankList(boolean custom) throws MediaException(Code) | | 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
MIDIControl.isBankQuerySupported isBankQuerySupported .
If it returns false, this function is not supported and throws an exception.
Parameters:
custom - if set to true, returns list of custom banks. an array of all installed bank numbers.Each bank number is in the range of 0..16383
exception:
MediaException - if this device does not support retrieval ofbanks
exception:
IllegalStateException - Thrown if the player has not been prefetched.
See Also: MIDIControl.isBankQuerySupported |
| getChannelVolume | | int getChannelVolume(int channel)(Code) | | Get volume for the given channel. The return value is
independent of the master volume, which is set and retrieved
with
VolumeControl 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 channel volume, 0-127, or -1 if not known
exception:
IllegalArgumentException - Thrown if channel is out of range.
exception:
IllegalStateException - Thrown if the player has not been prefetched.
See Also: MIDIControl.setChannelVolume(int,int) |
| getKeyName | | String getKeyName(int bank, int prog, int key) throws MediaException(Code) | | 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 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 which keys in a specific program
are mapped to a sound, iterate through all keys (0-127) and compare
the return value of getKeyName to non-null.
As there is no MIDI equivalent to this method, this method is
optional, indicated by
MIDIControl.isBankQuerySupported isBankQuerySupported .
If it returns false, this function is not supported and throws an exception.
Parameters:
bank - 0-16383
Parameters:
prog - 0-127
Parameters:
key - 0-127
exception:
IllegalArgumentException - Thrown if bank, prog or key is out of range.
exception:
MediaException - Thrown if the bank or program is not installed (internal or custom), or if this device does not support retrieval of key names
exception:
IllegalStateException - Thrown if the player has not been prefetched. name of the specified key, empty string, or null if the key is not mapped to a sound.
See Also: MIDIControl.isBankQuerySupported |
| getProgram | | int[] getProgram(int channel) throws MediaException(Code) | | 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
MIDIControl.isBankQuerySupported isBankQuerySupported .
If it returns false, this function is not supported and throws an exception.
Parameters:
channel - 0-15 program assigned to channel, represented by array {bank,program}.
exception:
IllegalArgumentException - Thrown if channel is out of range.
exception:
IllegalStateException - Thrown if the player has not been prefetched.
exception:
MediaException - Thrown if querying of banks is not supported.
See Also: MIDIControl.isBankQuerySupported
See Also: MIDIControl.setProgram |
| getProgramList | | int[] getProgramList(int bank) throws MediaException(Code) | | Given bank, get list of program numbers. If and 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
MIDIControl.isBankQuerySupported isBankQuerySupported .
If it returns false, this function is not supported and throws an exception.
Parameters:
bank - 0..16383 an array of programs defined in the given bank.Each program number is from 0..127.
exception:
IllegalArgumentException - Thrown if bank is out of range.
exception:
MediaException - Thrown if the device does not support retrieval of programs.
exception:
IllegalStateException - Thrown if the player has not been prefetched.
See Also: MIDIControl.setProgram
See Also: MIDIControl.isBankQuerySupported |
| getProgramName | | String getProgramName(int bank, int prog) throws MediaException(Code) | | 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
MIDIControl.isBankQuerySupported isBankQuerySupported .
If it returns false, this function is not supported and throws an exception.
Parameters:
bank - 0-16383
Parameters:
prog - 0-127
exception:
IllegalArgumentException - Thrown if bank or prog is out of range.
exception:
MediaException - Thrown if the bank or program is not installed (internal or custom), or if this device does not support retrieval of program names
exception:
IllegalStateException - Thrown if the player has not been prefetched. name of the specified program, or empty string.
See Also: MIDIControl.isBankQuerySupported |
| isBankQuerySupported | | boolean isBankQuerySupported()(Code) | | Returns whether banks of the synthesizer can be queried.
If this functions returns true,
then the following methods can be used to query banks:
true if this device supports querying of banks |
| longMidiEvent | | int longMidiEvent(byte[] data, int offset, int length)(Code) | | 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
Parameters:
offset - start offset in data array
Parameters:
length - number of bytes to be sent
exception:
IllegalArgumentException - Thrown if any one of the given parameters is not valid.
exception:
IllegalStateException - Thrown if the player has not been prefetched. the number of bytes actually sent to the device or-1 if an error occurred |
| setChannelVolume | | void setChannelVolume(int channel, int volume)(Code) | | 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 by 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 VolumeControl .
Setting the channel volume does not modify the value of the master
volume - and vice versa: changing the value of 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
javax.microedition.media.PlayerListener.VOLUME_CHANGED VOLUME_CHANGED event .
Parameters:
channel - 0-15
Parameters:
volume - 0-127
exception:
IllegalArgumentException - Thrown if channel or volume is out of range.
exception:
IllegalStateException - Thrown if the player has not been prefetched.
See Also: MIDIControl.getChannelVolume |
| setProgram | | void setProgram(int channel, int bank, int program)(Code) | | 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 parameter to -1.
In order to set 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
Parameters:
bank - 0-16383, or -1 for default bank
Parameters:
program - 0-127
exception:
IllegalArgumentException - Thrown if any of the given parameters is out of range.
exception:
IllegalStateException - Thrown if the player has not been prefetched.
See Also: MIDIControl.getProgram |
| shortMidiEvent | | void shortMidiEvent(int type, int data1, int data2)(Code) | | 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-0x0F).
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 IllegalArgumentException is thrown.
Parameters:
type - 0x80..0xFF, excluding 0xF0 and 0xF7, which are reserved for system exclusive
Parameters:
data1 - for 2 and 3-byte events: first data byte, 0..127
Parameters:
data2 - for 3-byte events: second data byte, 0..127
exception:
IllegalArgumentException - Thrown if one of the parameters is out of range.
exception:
IllegalStateException - Thrown if the player has not been prefetched. |
|
|