Module java.desktop

Package javax.sound.midi

Interface MidiChannel

       public interface MidiChannel
      

一个MidiChannel对象代表一个单独的MIDI通道。通常，每个MidiChannel方法处理一个与MIDI规范定义的同名MIDI“通道音频”或“通道模式”消息相似的消息。然而，MidiChannel添加了一些“获取”方法，用于检索最近由标准MIDI通道消息之一设置的值。类似地，还添加了用于每个通道的独奏和静音的方法。

Synthesizer对象有一组MidiChannels，通常每个通道对应MIDI 1.0规范中规定的16个通道之一。当MidiChannels接收到noteOn消息时，Synthesizer会生成声音。

有关MIDI通道消息的规定行为的更多信息，请参阅MIDI 1.0规范，这里没有详尽记录。该规范的标题是MIDI参考：完整的MIDI 1.0详细规范，由MIDI制造商协会（http://www.midi.org）发布。

MIDI最初是用于报告键盘音乐家的手势的协议。这种起源在MidiChannel API中可见，该API保留了诸如键号、键速度和键压力等MIDI概念。应该理解的是，MIDI数据不一定源自键盘演奏者（源可能是不同类型的音乐家或软件）。一些设备可能会生成恒定的速度和压力值，无论音符如何演奏。此外，MIDI规范通常让合成器自行决定如何使用数据。例如，速度数据不一定总是映射到音量和/或亮度。

参见：

• Synthesizer.getChannels()

Method Summary

Modifier and Type	Method	Description
void	allNotesOff()	关闭当前正在此通道上发出的所有音符。
void	allSoundOff()	立即关闭此通道上所有正在发出的音符，忽略踏板状态和当前Instrument的内部衰减率。
void	controlChange(int controller, int value)	对指定控制器值的更改做出反应。
int	getChannelPressure()	获取通道的键盘压力。
int	getController(int controller)	获取指定控制器的当前值。
boolean	getMono()	获取当前的单声道/多声道模式。
boolean	getMute()	获取此通道的当前静音状态。
boolean	getOmni()	获取当前的全音模式。
int	getPitchBend()	获取此通道的上行或下行音高偏移量。
int	getPolyPressure(int noteNumber)	获取正在按下指定键的压力。
int	getProgram()	获取此通道的当前程序号。
boolean	getSolo()	获取此通道的当前独奏状态。
boolean	localControl(boolean on)	打开或关闭本地控制。
void	noteOff(int noteNumber)	关闭指定的音符。
void	noteOff(int noteNumber, int velocity)	关闭指定的音符。
void	noteOn(int noteNumber, int velocity)	开始发出指定的音符。
void	programChange(int program)	更改程序（音色）。
void	programChange(int bank, int program)	使用银行和程序（音色）号更改程序。
void	resetAllControllers()	将所有实现的控制器重置为默认值。
void	setChannelPressure(int pressure)	对键盘压力的更改做出反应。
void	setMono(boolean on)	打开或关闭单声道模式。
void	setMute(boolean mute)	设置此通道的静音状态。
void	setOmni(boolean on)	打开或关闭全音模式。
void	setPitchBend(int bend)	更改此通道上所有音符的音高偏移量。
void	setPolyPressure(int noteNumber, int pressure)	对指定音符的键压力的更改做出反应。
void	setSolo(boolean soloState)	设置此通道的独奏状态。

Method Details

noteOn

             void noteOn(int noteNumber, int velocity)
            

开始发出指定的音符。按下速度通常控制音符的音量和/或亮度。如果velocity为零，则此方法将像noteOff(int)一样，终止音符。

参数：

noteNumber - MIDI音符号，从0到127（60 = 中央C）

velocity - 按下键的速度

参见：

• noteOff(int, int)

noteOff

             void noteOff(int noteNumber, int velocity)
            

关闭指定的音符。如果不忽略松开键的速度，则可以用来影响音符衰减的速度。无论如何，音符可能不会立即消失；其衰减速率由Instrument的内部确定。如果踏板（一个控制器；参见controlChange）处于按下状态，则此方法的效果将推迟到踏板释放时。

参数：

noteNumber - MIDI音符号，从0到127（60 = 中央C）

velocity - 松开键的速度

参见：

• noteOff(int)
• noteOn(int, int)
• allNotesOff()
• allSoundOff()

noteOff

             void noteOff(int noteNumber)
            

关闭指定的音符。

参数：

noteNumber - MIDI音符号，从0到127（60 = 中央C）

参见：

• noteOff(int, int)

setPolyPressure

             void setPolyPressure(int noteNumber, int pressure)
            

对指定音符的键压力的更改做出反应。多音键压力允许键盘演奏者同时按下多个键，每个键的压力不同。如果不忽略压力，则通常用于变化音符的音量、亮度或颤音等特性。

底层合成器可能不支持此MIDI消息。为了验证setPolyPressure是否成功，请使用getPolyPressure。

参数：

noteNumber - MIDI音符号，从0到127（60 = 中央C）

pressure - 指定键的值，从0到127（127 = 最大压力）

参见：

• getPolyPressure(int)

getPolyPressure

             int getPolyPressure(int noteNumber)
            

获取正在按下指定键的压力。

如果设备不支持设置多音键压力，则此方法始终返回0。然后调用setPolyPressure将不起作用。

参数：

noteNumber - MIDI音符号，从0到127（60 = 中央C）

返回：

该音符的压力量，从0到127（127 = 最大压力）

参见：

• setPolyPressure(int, int)

setChannelPressure

             void setChannelPressure(int pressure)
            

对键盘压力的更改做出反应。通道压力指示键盘演奏者正在按下整个键盘的力度。这可以是多个键的压力传感器值的最大值或平均值，由setPolyPressure设置。更常见的是，它是设备上的单个传感器的测量值，该设备不实现多音键压力。压力可用于控制声音的各个方面，如setPolyPressure下所述。

底层合成器可能不支持此MIDI消息。为了验证setChannelPressure是否成功，请使用getChannelPressure。

参数：

pressure - 键盘正在被按下的压力，从0到127（127 = 最大压力）

参见：

• setPolyPressure(int, int)
• getChannelPressure()

getChannelPressure

             int getChannelPressure()
            

获取通道的键盘压力。

如果设备不支持设置通道压力，则此方法始终返回0。然后调用setChannelPressure将不起作用。

返回：

该音符的压力量，从0到127（127 = 最大压力）

参见：

• setChannelPressure(int)

controlChange

             void controlChange(int controller, int value)
            

对指定控制器值的更改做出反应。控制器是除键盘键之外的某种控制，例如开关、滑块、踏板、轮子或呼吸压力传感器。MIDI 1.0规范为MIDI设备上的典型控制器提供了标准编号，并描述了某些控制器的预期效果。Instrument对控制器更改的反应方式可能特定于Instrument。

MIDI 1.0规范定义了7位控制器和14位控制器。连续控制器，如轮子和滑块，通常具有14位（两个MIDI字节），而离散控制器，如开关，通常具有7位（一个MIDI字节）。请参阅规范以查看每种控制类型的预期分辨率。

控制器64到95（0x40 - 0x5F）允许7位精度。7位控制器的值完全由value参数设置。另一组控制器通过使用两个控制器编号提供14位精度，一个用于最重要的7位，另一个用于最不重要的7位。控制器编号0到31（0x00 - 0x1F）控制14位控制器的最重要的7位；控制器编号32到63（0x20 - 0x3F）控制这些控制器的最不重要的7位。例如，控制器编号7（0x07）控制通道音量控制器的高7位，控制器编号39（0x27）控制低7位。14位控制器的值由两部分的交互确定。当设置控制器的最重要的7位（使用控制器编号0到31）时，最不重要的7位会自动设置为0。然后可以使用相应的控制器编号来进一步调制控制器值的值。

底层合成器可能不支持特定的控制器消息。为了验证对controlChange的调用是否成功，请使用getController。

参数:

controller - 控制器编号（0到127；请参阅MIDI 1.0规范以获取解释）

value - 指定控制器更改的值（0到127）

参见:

• getController(int)

getController

             int getController(int controller)
            

获取指定控制器的当前值。返回值用7位表示。对于14位控制器，需要分别获取MSB和LSB控制器值。例如，音量控制器的14位值可以通过将控制器7（0x07，通道音量MSB）的值乘以128并加上控制器39（0x27，通道音量LSB）的值来计算。

如果设备不支持设置特定控制器，则此方法对该控制器返回0。然后调用controlChange将不会产生任何效果。

参数:

controller - 欲获取值的控制器编号。允许范围为0-127；请参阅MIDI 1.0规范以获取解释。

返回:

指定控制器的当前值（0到127）

参见:

• controlChange(int, int)

programChange

             void programChange(int program)
            

更改程序（音色）。这会从当前选择的音色库中选择特定乐器。

MIDI规范未规定已发声音符是否应切换到新乐器（音色）或继续使用其原始音色直到由音符关闭终止。

程序编号是从零开始的（从0到127表示）。请注意，MIDI硬件显示和关于MIDI的文献通常使用范围1到128。

底层合成器可能不支持特定程序。为了验证对programChange的调用是否成功，请使用getProgram。

参数:

program - 要切换到的程序编号（0到127）

参见:

• programChange(int, int)
• getProgram()

programChange

             void programChange(int bank, int program)
            

使用音色库和程序（音色）编号更改程序。

底层合成器可能不支持特定音色库或程序。为了验证对programChange的调用是否成功，请使用getProgram和getController。由于音色库是通过控制变化来改变的，您可以使用以下语句验证当前音色库：

   int bank = (getController(0) * 128) + getController(32);
 

参数:

bank - 要切换到的音色库编号（0到16383）

program - 在指定音色库中使用的程序（音色）（0到127）

参见:

• programChange(int)
• getProgram()

getProgram

             int getProgram()
            

获取此通道的当前程序编号。

返回:

当前选择的音色的程序编号

参见:

• Patch.getProgram()
• Synthesizer.loadInstrument(javax.sound.midi.Instrument)
• programChange(int)

setPitchBend

             void setPitchBend(int bend)
            

更改此通道上所有音符的音高偏移。这会影响所有当前发声的音符以及随后的音符。（要停止音高弯曲，值需要重置到中心位置。）

MIDI规范规定音高弯曲是一个14位值，其中零是最大向下弯曲，16383是最大向上弯曲，8192是中心（无音高弯曲）。实际的音高变化量未指定；它可以通过音高灵敏度设置进行更改。但是，General MIDI规范表示默认范围应为中心向上和向下各两个半音。

底层合成器可能不支持此MIDI消息。为了验证setPitchBend是否成功，请使用getPitchBend。

参数:

bend - 音高变化量，作为非负的14位值（8192 = 无弯曲）

参见:

• getPitchBend()

getPitchBend

             int getPitchBend()
            

获取此通道的向上或向下音高偏移。如果设备不支持设置音高弯曲，则此方法始终返回8192。然后调用setPitchBend将不会产生任何效果。

返回:

音高弯曲量，作为非负的14位值（8192 = 无弯曲）

参见:

• setPitchBend(int)

resetAllControllers

             void resetAllControllers()
            

将所有实现的控制器重置为它们的默认值。

参见:

• controlChange(int, int)

allNotesOff

             void allNotesOff()
            

关闭此通道上当前发声的所有音符。音符可能不会立即消失；它们的衰减速率由Instrument的内部确定。如果踏板控制器（请参见controlChange）处于按下状态，则此方法的效果将推迟，直到踏板释放。

参见:

• allSoundOff()
• noteOff(int)

allSoundOff

             void allSoundOff()
            

立即关闭此通道上所有正在发声的音符，忽略踏板控制器的状态和当前Instrument的内部衰减速率。

参见:

• allNotesOff()

localControl

             boolean localControl(boolean on)
            

打开或关闭本地控制。默认情况下，本地控制是打开的。"打开"设置意味着如果设备能够既合成声音又发送MIDI消息，它将合成声音以响应自己发送的音符开和音符关消息。它还将响应从其他发送设备接收到的消息。"关闭"设置意味着合成器将忽略其自己发送的MIDI消息，但不会忽略从其他设备接收到的消息。

底层合成器可能不支持本地控制。为了验证对localControl的调用是否成功，请检查返回值。

参数:

on - true表示打开本地控制，false表示关闭本地控制

返回:

新的本地控制值，如果不支持本地控制则返回false

setMono

             void setMono(boolean on)
            

打开或关闭单声道模式。在单声道模式下，通道一次只合成一个音符。在多声道模式（与关闭单声道模式相同）下，通道可以同时合成多个音符。默认情况下，单声道模式关闭（多声道模式打开）。

"Mono"是"monophonic"一词的缩写，在此上下文中与"polyphonic"一词相对，指的是每个MIDI通道一个合成器音色声音。这与可能存在多少音频通道无关（如"monophonic"与"stereophonic"录音）。

底层合成器可能不支持单声道模式。为了验证对setMono的调用是否成功，请使用getMono。

参数:

on - true表示打开单声道模式，false表示关闭它（即打开多声道模式）

参见:

• getMono()
• VoiceStatus

getMono

             boolean getMono()
            

获取当前单声道/多声道模式。不允许更改单声道/多声道模式的合成器将始终返回相同的值，而不管对setMono的调用如何。

返回:

如果单声道模式打开，则为true，否则为false（表示多声道模式打开）

参见:

• setMono(boolean)

setOmni

             void setOmni(boolean on)
            

打开或关闭全音模式。在全音模式下，通道响应发送到所有通道的消息。当全音模式关闭时，通道仅响应发送到其通道编号的消息。默认情况下，全音模式关闭。

底层合成器可能不支持全音模式。为了验证setOmni是否成功，请使用getOmni。

参数:

on - true表示打开全音模式，false表示关闭它

参见:

• getOmni()
• VoiceStatus

getOmni

             boolean getOmni()
            

获取当前全音模式。不允许更改全音模式的合成器将始终返回相同的值，而不管对setOmni的调用如何。

返回:

如果全音模式打开，则为true，否则为false（表示全音模式关闭）

参见:

• setOmni(boolean)

setMute

             void setMute(boolean mute)
            

设置此通道的静音状态。值为true表示通道将被静音，false表示通道可以发声（如果其他通道未被独奏）。

与allSoundOff()不同，此方法仅适用于特定通道，而不是所有通道。此外，它不仅消除当前发声的音符，还消除随后接收到的音符。

底层合成器可能不支持静音通道。为了验证对setMute的调用是否成功，请使用getMute。

参数:

mute - 新的静音状态

参见:

• getMute()
• setSolo(boolean)

getMute

             boolean getMute()
            

获取此通道的当前静音状态。如果底层合成器不支持静音此通道，则此方法始终返回false。

返回：

true 通道已静音，或者false 未静音

另请参阅：

• setMute(boolean)

setSolo

             void setSolo(boolean soloState)
            

设置此通道的独奏状态。如果solo为true，则只有此通道和其他独奏通道会发声。如果solo为false，则只有其他独奏通道会发声，除非没有通道被独奏，此时所有未静音的通道会发声。

底层合成器可能不支持独奏通道。为了验证对setSolo的调用是否成功，请使用getSolo。

参数：

soloState - 通道的新独奏状态

另请参阅：

• getSolo()

getSolo

             boolean getSolo()
            

获取此通道的当前独奏状态。如果底层合成器不支持此通道的独奏，则此方法始终返回false。

返回：

true 通道已独奏，或者false 未独奏

另请参阅：

• setSolo(boolean)