javax.sound.midi

接口
类
异常

javax.sound.midi
接口 MidiChannel

public interface MidiChannel

表示一个单独 MIDI 通道的 MidiChannel 对象。通常，每个 MidiChannel 方法处理由 MIDI 规范定义的名称类似 MIDI “通道声音”或“通道模式”的消息。除此之外，MidiChannel 还添加了某些 "get" 方法，可检索由某个标准 MIDI 通道消息最近设置的值。类似地，也添加了用于检索每个通道的单声和静音值的方法。

Synthesizer 对象有一个 MidiChannel 集合，通常一个 MidiChannels 对应于 MIDI 1.0 规范规定的 16 个通道中的一个。Synthesizer 在其 MidiChannel 接收到 noteOn 消息时生成声音。

有关已规定的 MIDI 通道消息行为的更多信息，请参见 MIDI 1.0 规范，在此不加赘述。此规范名称为 MIDI Reference:The Complete MIDI 1.0 Detailed Specification，它由 MIDI 制造商协会 (http://www.midi.org) 发布。

MIDI 最初是一个用于报告键盘乐师动作的协议。在 MidiChannel API 中可以看出该起源的痕迹, 它保留了类似键号、键速度和键力度等 MIDI 概念。我们应该理解，MIDI 数据并不一定都起源于键盘演奏者（该源可以是另一类乐师或软件）。有些设备可以生成速度和力度的常数值，而不管如何演奏音符。同时，MIDI 规范通常让合成器根据实现程序的需要来决定数据的使用方式。例如，不一定需要始终将速度数据映射到音量和/或声音的亮度。

另请参见：
Synthesizer.getChannels()

方法摘要
 void allNotesOff()
          关闭此通道上当前发声的所有音符。
 void allSoundOff()
          立即关闭通道上所有发声的音符，同时忽略当前 Instrument 的 Hold Pedal 状态和内部衰减率。
 void controlChange(int controller, int value)
          对指定控件的值的更改作出反应。
 int getChannelPressure()
          获得通道的键盘力度。
 int getController(int controller)
          获得指定控件的当前值。
 boolean getMono()
          获得当前的 mono/poly 模式。
 boolean getMute()
          获得此通道的当前静音状态。
 boolean getOmni()
          获得当前的 omni 模式。
 int getPitchBend()
          获得此通道的向上或向下的音高偏移量。
 int getPolyPressure(int noteNumber)
          获得指定键被按下的力度。
 int getProgram()
          获得此通道的当前程序号。
 boolean getSolo()
          获得此通道的当前 solo 状态。
 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)
          打开或关闭 mono 模式。
 void setMute(boolean mute)
          设置此通道的静音状态。
 void setOmni(boolean on)
          打开或关闭 omni 模式。
 void setPitchBend(int bend)
          更改此通道上所有音符的音高偏移量。
 void setPolyPressure(int noteNumber, int pressure)
          对指定音符键力度的更改作出反应。
 void setSolo(boolean soloState)
          设置此通道的 solo 状态。
 

方法详细信息

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 的内部情况。如果按下 Hold Pedal（一种控件；请参见 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)
获得指定键被按下的力度。

参数：
noteNumber - MIDI 音符号，从 0 到 127（60 = 中央 C）。 如果设备不支持设置 PolyPressure，则此方法始终返回 0。这种情况下，调用 setPolyPressure 没有任何作用。
返回：
该音符的力度值，从 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()
获得通道的键盘力度。如果设备不支持设置 ChannelPressure，则此方法始终返回 0。这种情况下，调用 setChannelPressure 没有任何作用。

返回：
该音符的力度值，从 0 到 127（127 = 最大力度）
另请参见：
setChannelPressure(int)

controlChange

void controlChange(int controller,
                   int value)
对指定控件的值的更改作出反应。控件是指不同于键盘键的其他控制手段，例如开关、滑杆、踏板、滚轮或呼吸力度传感器。MIDI 1.0 Specification 提供了 MIDI 设备上的典型控件的标准号，并对某些控件的效果进行了描述。 Instrument 对控件更改的反应方式特定于 Instrument。

MIDI 1.0 Specification 同时定义了 7 位控件和 14 位控件。连续的控件，例如滚轮和滑杆通常为 14 位（两个 MIDI 字节），而离散的控件，例如开关，通常为 7 位（一个 MIDI 字节）。请参考规范，了解每种控制类型的具体精度。

控件 64 到 95 (0x40 - 0x5F) 允许 7 位精度。7 位控件的值完全通过 value 参数进行设置。其他的控件集通过使用两个控件号（一个用于最高有效 7 位，另一个用于最低有效 7 位）提供 14 位精度。控件号 0 到 31 (0x00 - 0x1F) 控制着 14 位控件的最高有效 7 位；控件号 32 到 63 (0x20 - 0x3F) 控制着这些控件的最低有效 7 位。例如，控件号 7 (0x07) 控制着通道音量控件的高 7 位，而控件号 39 (0x27) 则控制着低 7 位。14 位控件的值由这两个部分一起确定。当设置了控件的最高有效 7 位（使用控件号 0 到 31）时，低 7 位自动设置为 0。相应的用于低 7 位的控件号可用于进一步调整此控件值。 基础合成器可能不支持特定的控件消息。为了验证是否对 controlChange 进行了成功的调用，可使用 getController。

参数：
controller - 控件号（0 到 127；请参见 MIDI 1.0 Specification 中的解释）
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 Specification 中的解释。
返回：
指定控件的当前值（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)
更改此通道上所有音符的音高偏移量。这影响到所有当前发声的音符和后续的发声音符。（要停止使用弯音 (pitch bend)，需要将此值重置为中心位置）。

MIDI 规范规定弯音为一个 14 位值，其中，零为最大的向下弯音，16383 为最大的向上弯音，8192 位于中心位置（无弯音）。实际的音高更改量未指定；可由弯音微调设置对其进行更改。但是 General MIDI 规范指明，默认的范围应为距中心向上或向下的两个半音程。 基础合成器可能不支持此 MIDI 消息。为了验证 setPitchBend 设置是否成功，可使用 getPitchBend。

参数：
bend - 音高的更改量，它是一个非负的 14 位值（8192 = 无 bend）
另请参见：
getPitchBend()

getPitchBend

int getPitchBend()
获得此通道的向上或向下的音高偏移量。如果设备不支持设置弯音，则此方法始终返回 8192。这种情况下，调用 setPitchBend 没有任何作用。

返回：
弯音量，它是一个非负的 14 位值（8192 = 无 bend）
另请参见：
setPitchBend(int)

resetAllControllers

void resetAllControllers()
将所有实现的控件重置为其默认值。

另请参见：
controlChange(int, int)

allNotesOff

void allNotesOff()
关闭此通道上当前发声的所有音符。音符不太可能立即消失；它们的衰减率取决于 Instrument 的内部情况。如果按下 Hold Pedal 控件（请参见 controlChange），则此方法的效果要推迟到踏板释放时才能体现。

另请参见：
allSoundOff(), noteOff(int)

allSoundOff

void allSoundOff()
立即关闭通道上所有发声的音符，同时忽略当前 Instrument 的 Hold Pedal 状态和内部衰减率。

另请参见：
allNotesOff()

localControl

boolean localControl(boolean on)
打开或关闭本地控制。本地控制在默认情况下是开启的。 "on" 设置表示如果设备能够合成声音并传输 MIDI 消息，则它将合成声音作为对它本身所传输的音符打开和音符关闭消息的响应。它还将响应从其他传输设备接收到的消息。"off" 设置表示合成器将忽略其自身传输的 MIDI 消息，但不忽略从其他设备接收到的消息。 基础合成器可能不支持本地控制。为了验证是否对 localControl 行了成功的调用，请检查返回值。

参数：
on - true 可打开本地控制， false 则关闭本地控制
返回：
新的本地控制值，如果不支持本地控制，则返回 false

setMono

void setMono(boolean on)
打开或关闭 mono 模式。在 mono 模式下，通道一次只合成一个音符。在 poly 模式（等效于 mono 模式关闭）下，通道可同步合成多个音符。默认情况下 mono 为关闭（poly 模式为打开）。

"Mono" 是 "monophonic"（单声道）的简写，在此上下文中与 "polyphonic"（复调）相反，指的是每个 MIDI 通道有单个合成器声音。它与音频通道数没有任何关系（即“单声道”和“立体声”录音的情况）。 基础合成器可能不支持 mono 模式。为了验证是否对 setMono 进行了成功的调用，可使用 getMono。

参数：
on - true 为打开 mono 模式， false 为关闭 mono 模式（表示打开 poly 模式）。
另请参见：
getMono(), VoiceStatus

getMono

boolean getMono()
获得当前的 mono/poly 模式。无论如何调用 setMono，不允许更改 mono/poly 模式的合成器将始终返回相同的值。

返回：
如果 mono 模式为打开，则返回 true，否则返回 false（表示 poly 模式为打开）。
另请参见：
setMono(boolean)

setOmni

void setOmni(boolean on)
打开或关闭 omni 模式。在 omni 模式下，通道会响应发送到所有通道上的消息。omni 为关闭时，通道只响应发送到其通道号上的消息。默认情况下 omni 为关闭。 基础合成器可能不支持 omni 模式。为了验证 setOmni 设置是否成功，可使用 getOmni。

参数：
on - true 表示开启 omni 模式， false 表示关闭 omni 模式。
另请参见：
getOmni(), VoiceStatus

getOmni

boolean getOmni()
获得当前的 omni 模式。无论如何调用 setOmni，不允许更改 omni 模式的合成器将始终返回相同的值。

返回：
如果 omni 模式为打开，则返回 true，否则返回 false（表示 omni 模式为关闭）。
另请参见：
setOmni(boolean)

setMute

void setMute(boolean mute)
设置此通道的静音状态。值为 true 表示该通道将设置为静音，值为 false 表示该通道可发声（如果其他通道为非 solo）。

与 allSoundOff() 不同，此方法只适用于特定的通道，而不是所有的通道。更进一步地说，它不只将当前发声的音符设置为静音，而且将后续接收的音符都设置为静音。 基础合成器可能不支持静音通道。为了验证是否对 setMute 进行了成功的调用，可使用 getMute。

参数：
mute - 新的静音状态
另请参见：
getMute(), setSolo(boolean)

getMute

boolean getMute()
获得此通道的当前静音状态。如果基础合成器不支持对此通道的静音设置，则此方法始终返回 false。

返回：
通道为静音设置，则返回 true，否则返回 false
另请参见：
setMute(boolean)

setSolo

void setSolo(boolean soloState)
设置此通道的 solo 状态。如果 solo 为 true，则只有此通道及其他 solo 通道可发声。如果 solo 为 false，则只有其他 solo 通道可发声；除非在没有 solo 通道的情况下，所有非静音通道都发声。 基础合成器可能不支持 solo 通道。为了验证是否对 setSolo 进行了成功的调用，可使用 getSolo。

参数：
soloState - 该通道的新 solo 状态
另请参见：
getSolo()

getSolo

boolean getSolo()
获得此通道的当前 solo 状态。如果基础合成器不支持此通道上的 solo，则此方法始终返回 false。

返回：
如果通道为 solo，则返回 true，否则返回 false
另请参见：
setSolo(boolean)