File	Doc	Category	Size	Date	Package
MIDIControl.java	API Doc	phoneME MR2 API (J2ME)	19420	Wed May 02 16:47:14 BST 2007	javax.microedition.media.control

MIDIControl

Fields Summary
int	NOTE_ON 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.
int	CONTROL_CHANGE Command value for Control Change message (0xB0, or 176).

Constructors Summary

Methods Summary
public 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 {@link #isBankQuerySupported isBankQuerySupported}. If it returns false, this function is not supported and throws an exception. param custom if set to true, returns list of custom banks. return 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 of banks exception IllegalStateException Thrown if the player has not been prefetched. see #isBankQuerySupported
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 {@link 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. param channel 0-15 return 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 #setChannelVolume(int, int)
public java.lang.String	getKeyName(int bank, int prog, int key) 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 {@link #isBankQuerySupported isBankQuerySupported}. If it returns false, this function is not supported and throws an exception. param bank 0-16383 param prog 0-127 param 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. return name of the specified key, empty string, or null if the key is not mapped to a sound. see #isBankQuerySupported
public int[]	getProgram(int channel) 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 {@link #isBankQuerySupported isBankQuerySupported}. If it returns false, this function is not supported and throws an exception. param channel 0-15 return 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 #isBankQuerySupported see #setProgram
public int[]	getProgramList(int bank) 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 {@link #isBankQuerySupported isBankQuerySupported}. If it returns false, this function is not supported and throws an exception. param bank 0..16383 return 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 #setProgram see #isBankQuerySupported
public java.lang.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 {@link #isBankQuerySupported isBankQuerySupported}. If it returns false, this function is not supported and throws an exception. param bank 0-16383 param 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. return name of the specified program, or empty string. see #isBankQuerySupported
public boolean	isBankQuerySupported() Returns whether banks of the synthesizer can be queried. If this functions returns true, then the following methods can be used to query banks: {@link #getProgram(int) getProgram(int)} {@link #getBankList(boolean) getBankList(boolean)} {@link #getProgramList(int) getProgramList(int)} {@link #getProgramName(int, int) getProgramName(int, int)} {@link #getKeyName(int, int, int) getKeyName(int, int, int)} return true if this device supports querying of banks
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. param data array of the bytes to send param offset start offset in data array param 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. return the number of bytes actually sent to the device or -1 if an error occurred
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 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 {@link 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 {@link javax.microedition.media.PlayerListener#VOLUME_CHANGED VOLUME_CHANGED event}. param channel 0-15 param 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 #getChannelVolume
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 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; param channel 0-15 param bank 0-16383, or -1 for default bank param 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 #getProgram
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-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. param type 0x80..0xFF, excluding 0xF0 and 0xF7, which are reserved for system exclusive param data1 for 2 and 3-byte events: first data byte, 0..127 param 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.