public interface MidiChannel
MidiChannel
object represents a single MIDI channel. Generally, each MidiChannel
method processes a like-named MIDI "channel voice" or "channel mode" message as defined by the MIDI specification. However, MidiChannel
adds some "get" methods that retrieve the value most recently set by one of the standard MIDI channel messages. Similarly, methods for per-channel solo and mute have been added. A Synthesizer
object has a collection of MidiChannels
, usually one for each of the 16 channels prescribed by the MIDI 1.0 specification. The Synthesizer
generates sound when its MidiChannels
receive noteOn
messages.
See the MIDI 1.0 Specification for more information about the prescribed behavior of the MIDI channel messages, which are not exhaustively documented here. The specification is titled MIDI Reference: The Complete MIDI 1.0 Detailed Specification
, and is published by the MIDI Manufacturer's Association (http://www.midi.org).
MIDI was originally a protocol for reporting the gestures of a keyboard musician. This genesis is visible in the MidiChannel
API, which preserves such MIDI concepts as key number, key velocity, and key pressure. It should be understood that the MIDI data does not necessarily originate with a keyboard player (the source could be a different kind of musician, or software). Some devices might generate constant values for velocity and pressure, regardless of how the note was performed. Also, the MIDI specification often leaves it up to the synthesizer to use the data in the way the implementor sees fit. For example, velocity data need not always be mapped to volume and/or brightness.
Modifier and Type | Method | Description |
---|---|---|
void |
allNotesOff() |
Turns off all notes that are currently sounding on this channel. |
void |
allSoundOff() |
Immediately turns off all sounding notes on this channel, ignoring the state of the Hold Pedal and the internal decay rate of the current Instrument . |
void |
controlChange |
Reacts to a change in the specified controller's value. |
int |
getChannelPressure() |
Obtains the channel's keyboard pressure. |
int |
getController |
Obtains the current value of the specified controller. |
boolean |
getMono() |
Obtains the current mono/poly mode. |
boolean |
getMute() |
Obtains the current mute state for this channel. |
boolean |
getOmni() |
Obtains the current omni mode. |
int |
getPitchBend() |
Obtains the upward or downward pitch offset for this channel. |
int |
getPolyPressure |
Obtains the pressure with which the specified key is being depressed. |
int |
getProgram() |
Obtains the current program number for this channel. |
boolean |
getSolo() |
Obtains the current solo state for this channel. |
boolean |
localControl |
Turns local control on or off. |
void |
noteOff |
Turns the specified note off. |
void |
noteOff |
Turns the specified note off. |
void |
noteOn |
Starts the specified note sounding. |
void |
programChange |
Changes a program (patch). |
void |
programChange |
Changes the program using bank and program (patch) numbers. |
void |
resetAllControllers() |
Resets all the implemented controllers to their default values. |
void |
setChannelPressure |
Reacts to a change in the keyboard pressure. |
void |
setMono |
Turns mono mode on or off. |
void |
setMute |
Sets the mute state for this channel. |
void |
setOmni |
Turns omni mode on or off. |
void |
setPitchBend |
Changes the pitch offset for all notes on this channel. |
void |
setPolyPressure |
Reacts to a change in the specified note's key pressure. |
void |
setSolo |
Sets the solo state for this channel. |
void noteOn(int noteNumber, int velocity)
velocity
is zero, this method instead acts like noteOff(int)
, terminating the note.noteNumber
- the MIDI note number, from 0 to 127 (60 = Middle C)velocity
- the speed with which the key was depressedvoid noteOff(int noteNumber, int velocity)
Instrument
. If the Hold Pedal (a controller; see controlChange
) is down, the effect of this method is deferred until the pedal is released.noteNumber
- the MIDI note number, from 0 to 127 (60 = Middle C)velocity
- the speed with which the key was releasedvoid noteOff(int noteNumber)
noteNumber
- the MIDI note number, from 0 to 127 (60 = Middle C)void setPolyPressure(int noteNumber, int pressure)
It is possible that the underlying synthesizer does not support this MIDI message. In order to verify that setPolyPressure
was successful, use getPolyPressure
.
noteNumber
- the MIDI note number, from 0 to 127 (60 = Middle C)pressure
- value for the specified key, from 0 to 127 (127 = maximum pressure)int getPolyPressure(int noteNumber)
If the device does not support setting poly pressure, this method always returns 0. Calling setPolyPressure
will have no effect then.
noteNumber
- the MIDI note number, from 0 to 127 (60 = Middle C)void setChannelPressure(int pressure)
setPolyPressure
. More commonly, it is a measurement of a single sensor on a device that doesn't implement polyphonic key pressure. Pressure can be used to control various aspects of the sound, as described under setPolyPressure
. It is possible that the underlying synthesizer does not support this MIDI message. In order to verify that setChannelPressure
was successful, use getChannelPressure
.
pressure
- the pressure with which the keyboard is being depressed, from 0 to 127 (127 = maximum pressure)int getChannelPressure()
If the device does not support setting channel pressure, this method always returns 0. Calling setChannelPressure
will have no effect then.
void controlChange(int controller, int value)
Instrument
reacts to a controller change may be specific to the Instrument
. The MIDI 1.0 Specification defines both 7-bit controllers and 14-bit controllers. Continuous controllers, such as wheels and sliders, typically have 14 bits (two MIDI bytes), while discrete controllers, such as switches, typically have 7 bits (one MIDI byte). Refer to the specification to see the expected resolution for each type of control.
Controllers 64 through 95 (0x40 - 0x5F) allow 7-bit precision. The value of a 7-bit controller is set completely by the value
argument. An additional set of controllers provide 14-bit precision by using two controller numbers, one for the most significant 7 bits and another for the least significant 7 bits. Controller numbers 0 through 31 (0x00 - 0x1F) control the most significant 7 bits of 14-bit controllers; controller numbers 32 through 63 (0x20 - 0x3F) control the least significant 7 bits of these controllers. For example, controller number 7 (0x07) controls the upper 7 bits of the channel volume controller, and controller number 39 (0x27) controls the lower 7 bits. The value of a 14-bit controller is determined by the interaction of the two halves. When the most significant 7 bits of a controller are set (using controller numbers 0 through 31), the lower 7 bits are automatically set to 0. The corresponding controller number for the lower 7 bits may then be used to further modulate the controller value.
It is possible that the underlying synthesizer does not support a specific controller message. In order to verify that a call to controlChange
was successful, use getController
.
controller
- the controller number (0 to 127; see the MIDI 1.0 Specification for the interpretation)value
- the value to which the specified controller is changed (0 to 127)int getController(int controller)
If the device does not support setting a specific controller, this method returns 0 for that controller. Calling controlChange
will have no effect then.
controller
- the number of the controller whose value is desired. The allowed range is 0-127; see the MIDI 1.0 Specification for the interpretation.void programChange(int program)
The MIDI specification does not dictate whether notes that are already sounding should switch to the new instrument (timbre) or continue with their original timbre until terminated by a note-off.
The program number is zero-based (expressed from 0 to 127). Note that MIDI hardware displays and literature about MIDI typically use the range 1 to 128 instead.
It is possible that the underlying synthesizer does not support a specific program. In order to verify that a call to programChange
was successful, use getProgram
.
program
- the program number to switch to (0 to 127)void programChange(int bank, int program)
It is possible that the underlying synthesizer does not support a specific bank, or program. In order to verify that a call to programChange
was successful, use getProgram
and getController
. Since banks are changed by way of control changes, you can verify the current bank with the following statement:
int bank = (getController(0) * 128) + getController(32);
bank
- the bank number to switch to (0 to 16383)program
- the program (patch) to use in the specified bank (0 to 127)int getProgram()
void setPitchBend(int bend)
The MIDI specification stipulates that pitch bend be a 14-bit value, where zero is maximum downward bend, 16383 is maximum upward bend, and 8192 is the center (no pitch bend). The actual amount of pitch change is not specified; it can be changed by a pitch-bend sensitivity setting. However, the General MIDI specification says that the default range should be two semitones up and down from center.
It is possible that the underlying synthesizer does not support this MIDI message. In order to verify that setPitchBend
was successful, use getPitchBend
.
bend
- the amount of pitch change, as a nonnegative 14-bit value (8192 = no bend)int getPitchBend()
setPitchBend
will have no effect then.void resetAllControllers()
void allNotesOff()
Instrument
. If the Hold Pedal controller (see controlChange
) is down, the effect of this method is deferred until the pedal is released.void allSoundOff()
Instrument
.boolean localControl(boolean on)
It is possible that the underlying synthesizer does not support local control. In order to verify that a call to localControl
was successful, check the return value.
on
- true
to turn local control on, false
to turn local control offvoid setMono(boolean on)
"Mono" is short for the word "monophonic," which in this context is opposed to the word "polyphonic" and refers to a single synthesizer voice per MIDI channel. It has nothing to do with how many audio channels there might be (as in "monophonic" versus "stereophonic" recordings).
It is possible that the underlying synthesizer does not support mono mode. In order to verify that a call to setMono
was successful, use getMono
.
on
- true
to turn mono mode on, false
to turn it off (which means turning poly mode on)boolean getMono()
setMono
.true
if mono mode is on, otherwise false
(meaning poly mode is on)void setOmni(boolean on)
It is possible that the underlying synthesizer does not support omni mode. In order to verify that setOmni
was successful, use getOmni
.
on
- true
to turn omni mode on, false
to turn it offboolean getOmni()
setOmni
.true
if omni mode is on, otherwise false
(meaning omni mode is off)void setMute(boolean mute)
true
means the channel is to be muted, false
means the channel can sound (if other channels are not soloed). Unlike allSoundOff()
, this method applies to only a specific channel, not to all channels. Further, it silences not only currently sounding notes, but also subsequently received notes.
It is possible that the underlying synthesizer does not support muting channels. In order to verify that a call to setMute
was successful, use getMute
.
mute
- the new mute stateboolean getMute()
false
.true
the channel is muted, or false
if notvoid setSolo(boolean soloState)
solo
is true
only this channel and other soloed channels will sound. If solo
is false
then only other soloed channels will sound, unless no channels are soloed, in which case all unmuted channels will sound. It is possible that the underlying synthesizer does not support solo channels. In order to verify that a call to setSolo
was successful, use getSolo
.
soloState
- new solo state for the channelboolean getSolo()
false
.true
the channel is solo, or false
if not
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/sound/midi/MidiChannel.html