javax.sound.midi
接口 Sequencer

所有超级接口：

MidiDevice

public interface Sequencer
extends MidiDevice

回放 MIDI sequence 的硬件或软件设备就是所谓的 sequencer。MIDI sequence 包含加了时间戳的 MIDI 数据列表，例如可从标准 MIDI 文件读取的数据。多数 sequencer 还提供创建和编辑 sequence 的功能。

Sequencer 接口包括用于以下基本 MIDI sequencer 操作的方法：

• 从 MIDI 文件数据获取一个 sequence
• 开始和停止回放
• 移动到 sequence 中的任意位置
• 更改回放速度
• 将回放与内部时钟或接收到的 MIDI 消息同步
• 控制另一个设备的定时

• 通过添加或删除单独 MIDI 事件或整个轨道来编辑数据
• 对 sequence 中的单独轨道静音或执行独奏
• 通知 listener 对象有关回放 sequence 时遇到的任何元事件或控制更改事件。

另请参见：

Sequencer.SyncMode, addMetaEventListener(javax.sound.midi.MetaEventListener), ControllerEventListener, Receiver, Transmitter, MidiDevice

LOOP_CONTINUOUSLY

static final int LOOP_CONTINUOUSLY

一个值，指示循环应无限继续而不是在执行完特定次数的循环后停止。

从以下版本开始：

1.5

另请参见：

setLoopCount(int), 常量字段值

setSequence

void setSequence(Sequence sequence)
                 throws InvalidMidiDataException

设置 sequencer 所操作的当前 sequence。

此方法即使在 Sequencer 关闭时也可调用。

参数：

sequence - 要加载的 sequence。

抛出：

InvalidMidiDataException - 如果该 sequence 包含无效的 MIDI 数据或不受支持的数据。

setSequence

void setSequence(InputStream stream)
                 throws IOException,
                        InvalidMidiDataException

设置 sequencer 所操作的当前 sequence。该流必须指向 MIDI 文件数据。

此方法即使在 Sequencer 关闭时也可调用。

参数：

stream - 包含 MIDI 文件数据的流。

抛出：

IOException - 如果读取流时发生 I/O 异常。

InvalidMidiDataException - 如果在流中遇到无效数据，或者流不受支持。

getSequence

Sequence getSequence()

获得 Sequencer 当前所操作的 sequence。

此方法即使在 Sequencer 关闭时也可调用。

返回：

当前的 sequence，如果当前未设置任何 sequence，则返回 null。

start

void start()

开始回放当前已加载 sequence 中的 MIDI 数据。回放将从当前位置开始。如果回放位置到达循环终点，并且循环计数大于 0，则回放将从循环开始点继续运行 setLoopCount 中设置的重复次数。此后，如果循环计数为 0，则回放将继续播放直到 sequence 末尾。

该实现确保合成器在跳转到循环开始点时通过发送合适的控件、弯音和程序更改事件来保持一致的状态。

抛出：

IllegalStateException - 如果 Sequencer 已关闭。

另请参见：

setLoopStartPoint(long), setLoopEndPoint(long), setLoopCount(int), stop()

stop

void stop()

停止录音（如果处于活动状态）及当前已加载 sequence（如果有）的回放。

抛出：

IllegalStateException - 如果 Sequencer 已关闭。

另请参见：

start(), isRunning()

isRunning

boolean isRunning()

指示 Sequencer 当前是否正在运行。默认值为 false。Sequencer 在调用 start() 或 startRecording() 之一时开始运行。然后 isRunning 返回 true，直到 sequence 的回放完成或调用了 stop()。

返回：

如果 Sequencer 正在运行中，则返回 true；否则返回 false

startRecording

void startRecording()

开始录制和回放 MIDI 数据。数据录制到为其启用的通道上的所有已启用音轨上。录制从 sequencer 的当前位置开始。录制会话过程中重写音轨上的全部已有事件。取自当前已加载 sequence 的事件（如果有）随录制过程中接收的消息传递给 sequencer 的传输器。

注意，默认不允许轨道进行录制。为了录制 MIDI 数据，必须至少指定一个轨道允许录制。

抛出：

IllegalStateException - 如果 Sequencer 已关闭。

另请参见：

startRecording(), recordEnable(javax.sound.midi.Track, int), recordDisable(javax.sound.midi.Track)

stopRecording

void stopRecording()

停止录制（如果处于活动状态）。继续当前 sequence 的回放。

抛出：

IllegalStateException - 如果 Sequencer 已关闭。

另请参见：

startRecording(), isRecording()

isRecording

boolean isRecording()

指示 Sequencer 当前是否正在录制。默认值为 false。Sequencer 在 startRecording() 调用时开始录制，然后在调用 stop() 或 stopRecording() 前，此方法返回 true。

返回：

如果 Sequencer 正在录制中，则返回 true；否则返回 false

recordEnable

void recordEnable(Track track,
                  int channel)

为录制特定通道上接收的事件准备指定的轨道。一旦启用，轨道将在录制处于活动状态时接收事件。

参数：

track - 要录制事件的轨道

channel - 接收其上事件的通道。如果通道值指定为 -1，则轨道将从所有通道接收数据。

抛出：

IllegalArgumentException - 如果 track 不是当前 sequence 的一部分。

recordDisable

void recordDisable(Track track)

禁止向指定轨道的录制。事件将不再录制到此轨道中。

参数：

track - 要禁止录制的轨道，或为 null 以禁止录制到所有轨道。

getTempoInBPM

float getTempoInBPM()

获得当前的速度，用每分钟的拍数表示。实际的回放速度是返回值和速度因子的乘积。

返回：

当前的速度，用每分钟的拍数表示

另请参见：

getTempoFactor(), setTempoInBPM(float), getTempoInMPQ()

setTempoInBPM

void setTempoInBPM(float bpm)

设置速度，以每分钟的拍数为单位。实际的回放速度是指定值和速度因子的乘积。

参数：

bpm - 所需的新速度，以每分钟的拍数为单位

另请参见：

getTempoFactor(), setTempoInMPQ(float), getTempoInBPM()

getTempoInMPQ

float getTempoInMPQ()

获得当前的速度，用每四分音符的微秒数表示。实际的回放速度是返回值和速度因子的乘积。

返回：

当前的速度，以每四分音符的微秒数为单位

另请参见：

getTempoFactor(), setTempoInMPQ(float), getTempoInBPM()

setTempoInMPQ

void setTempoInMPQ(float mpq)

设置速度，以每四分音符的微秒数为单位。实际的回放速度是指定值和速度因子的乘积。

参数：

mpq - 所需的新速度，以每四分音符的微秒数为单位。

另请参见：

getTempoFactor(), setTempoInBPM(float), getTempoInMPQ()

setTempoFactor

void setTempoFactor(float factor)

根据所提供的 factor 按比例提高 sequencer 的实际回放速度。默认值是 1.0。值为 1.0 表示固有的速率（sequence 中指定的速度），2.0 表示速度为两倍大小，依此类推。速度因子并不影响 getTempoInMPQ() 和 getTempoInBPM() 返回的值。这些值指示提高速度前的速度。

注意，在使用外部同步时无法调整速度因子。这种情况下，setTempoFactor 始终将速度因子设置为 1.0。

参数：

factor - 所请求的速度标量

另请参见：

getTempoFactor()

getTempoFactor

float getTempoFactor()

返回 sequencer 的当前速度因子。默认值是 1.0。

返回：

速度因子。

另请参见：

setTempoFactor(float)

getTickLength

long getTickLength()

获得当前 sequence 的长度，用 MIDI 节拍数表示，如果未设置 sequence，则为 0。

返回：

sequence 的长度，以节拍数为单位

getTickPosition

long getTickPosition()

获得 sequence 的当前位置，用 MIDI 节拍数表示。（节拍持续的秒数由速度和存储在 Sequence 中的定时精度确定。）

返回：

当前节拍

另请参见：

setTickPosition(long)

setTickPosition

void setTickPosition(long tick)

设置当前 sequencer 位置，以 MIDI 节拍数为单位。

参数：

tick - 所需的节拍位置

另请参见：

getTickPosition()

getMicrosecondLength

long getMicrosecondLength()

获得当前 sequence 的长度，用微秒表示，如果未设置 sequence，则为 0。

返回：

sequence 的长度，用微秒表示。

getMicrosecondPosition

long getMicrosecondPosition()

获得 sequence 中的当前位置，用微秒表示。

指定者：

接口 MidiDevice 中的 getMicrosecondPosition

返回：

当前位置，用微秒表示

另请参见：

setMicrosecondPosition(long)

setMicrosecondPosition

void setMicrosecondPosition(long microseconds)

设置 sequence 中的当前位置，用微秒表示

参数：

microseconds - 所需的位置，以微秒为单位

另请参见：

getMicrosecondPosition()

setMasterSyncMode

void setMasterSyncMode(Sequencer.SyncMode sync)

设置此 sequencer 使用的定时信息源。Sequencer 与主同步模式同步，主同步模式为内部时钟、MIDI 时钟和 MIDI 时间代码，具体取决于 sync 的值。sync 参数必须是所支持的模式之一，如 getMasterSyncModes() 返回的结果。

参数：

sync - 所需的主同步模式

另请参见：

Sequencer.SyncMode.INTERNAL_CLOCK, Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, getMasterSyncMode()

getMasterSyncMode

Sequencer.SyncMode getMasterSyncMode()

获得此 sequencer 的当前主同步模式。

返回：

当前的主同步模式

另请参见：

setMasterSyncMode(Sequencer.SyncMode), getMasterSyncModes()

getMasterSyncModes

Sequencer.SyncMode[] getMasterSyncModes()

获得此 sequencer 支持的主同步模式集。

返回：

可用的主同步模式

另请参见：

Sequencer.SyncMode.INTERNAL_CLOCK, Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, getMasterSyncMode(), setMasterSyncMode(Sequencer.SyncMode)

setSlaveSyncMode

void setSlaveSyncMode(Sequencer.SyncMode sync)

设置此 sequencer 的从同步模式。这指示由 sequencer 发送到接收器的定时信息类型。sync 参数必须是所支持的模式之一，如 getSlaveSyncModes() 返回的结果。

参数：

sync - 所需的从同步模式

另请参见：

Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, Sequencer.SyncMode.NO_SYNC, getSlaveSyncModes()

getSlaveSyncMode

Sequencer.SyncMode getSlaveSyncMode()

获得此 sequencer 的当前从同步模式。

返回：

当前的从同步模式

另请参见：

setSlaveSyncMode(Sequencer.SyncMode), getSlaveSyncModes()

getSlaveSyncModes

Sequencer.SyncMode[] getSlaveSyncModes()

获得此 sequencer 支持的从同步模式集。

返回：

可用的从同步模式

另请参见：

Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, Sequencer.SyncMode.NO_SYNC

setTrackMute

void setTrackMute(int track,
                  boolean mute)

设置轨道的静音状态。此方法可能由于某些原因而失败。例如，所指定的轨道号可能对于当前 sequence 无效，或者 sequencer 可能不支持此功能。需要验证此操作是否成功的应用程序应在此调用后调用 getTrackMute(int)。

参数：

track - 轨道号。当前 sequence 中的轨道从 0 到 sequence 中的轨道数减 1 来编号。

mute - 轨道的新静音状态。true 表示轨道应静音，false 表示轨道应为非静音。

另请参见：

getSequence()

getTrackMute

boolean getTrackMute(int track)

获得轨道的当前静音状态。未静音前所有轨道的默认静音状态都是 false。在任何指定轨道未静音的情况下，此方法应返回 false。这适用于当 sequencer 不支持轨道静音并且指定的轨道索引无效的情况。

参数：

track - 轨道号。当前 sequence 中的轨道从 0 到 sequence 中的轨道数减 1 来编号。

返回：

如果已静音，则返回 true；如果未静音，则返回 false。

setTrackSolo

void setTrackSolo(int track,
                  boolean solo)

设置轨道的 solo 状态。如果 solo 为 true，则只有此轨道及其他 solo 轨道可发声。如果 solo 为 false，则只有其他 solo 轨道可发声，如果没有任何 solo 轨道，则所有非静音轨道都发声。

此方法可能由于某些原因而失败。例如，所指定的轨道号可能对于当前 sequence 无效，或者 sequencer 可能不支持此功能。需要验证此操作是否成功的应用程序应在此调用后调用 getTrackSolo(int)。

参数：

track - 轨道号。当前 sequence 中的轨道从 0 到 sequence 中的轨道数减 1 来编号。

solo - 轨道的新 solo 状态。true 表示轨道应为 solo，false 表示轨道应为非 solo。

另请参见：

getSequence()

getTrackSolo

boolean getTrackSolo(int track)

获得轨道的当前 solo 状态。未 solo 前所有轨道的默认静音状态都是 false。在任何指定轨道未 solo 的情况下，此方法应返回 false。这适用于当 sequencer 不支持轨道 solo 并且指定的轨道索引无效的情况。

参数：

track - 轨道号。当前 sequence 中的轨道从 0 到 sequence 中的轨道数减 1 来编号。

返回：

如果已为 solo，则返回 true；如果不是，则返回 false。

addMetaEventListener

boolean addMetaEventListener(MetaEventListener listener)

注册一个元事件侦听器，以便在 sequence 中遇到元事件并由此 sequencer 处理时接收通知。此方法在此 sequencer 类不支持元事件通知时会失败。

参数：

listener - 要添加的侦听器

返回：

如果成功添加了该侦听器，则返回 true；否则返回 false

另请参见：

removeMetaEventListener(javax.sound.midi.MetaEventListener), MetaEventListener, MetaMessage

removeMetaEventListener

void removeMetaEventListener(MetaEventListener listener)

从此 sequencer 的已注册侦听器列表中移除指定的元事件侦听器（如果实际上此侦听器已注册）。

参数：

listener - 要移除的元事件侦听器

另请参见：

addMetaEventListener(javax.sound.midi.MetaEventListener)

addControllerEventListener

int[] addControllerEventListener(ControllerEventListener listener,
                                 int[] controllers)

注册一个控件事件侦听器，以便在 sequencer 处理所请求的一种或多种类型的控制更改事件时接收通知。类型由 controllers 参数指定，该参数应包含一个 MIDI 控件号的数组。（每个编号应该是 0 到 127（包括）之间的一个数。请参见 MIDI 1.0 规范中与各种类型控件对应的编号。）

返回的数组包含 MIDI 控件号，侦听器将从现在开始接收其事件。有些 sequencer 可能不支持控件事件通知，这种情况下数组长度为 0。其他 sequencer 可能支持某些控件的通知，但不是全部。此方法可重复调用。每次调用时，返回的数组都指示侦听器将接收其通知的所有控件，而不仅仅是在该特定调用中请求的控件。

参数：

listener - 要添加到已注册侦听器列表中的控件事件侦听器

controllers - 为其请求更改通知的 MIDI 控件号

返回：

其更改将报告给指定侦听器的所有 MIDI 控件号

另请参见：

removeControllerEventListener(javax.sound.midi.ControllerEventListener, int[]), ControllerEventListener

removeControllerEventListener

int[] removeControllerEventListener(ControllerEventListener listener,
                                    int[] controllers)

移除侦听一类或多类控件事件的控件事件侦听器。controllers 参数使用一个 MIDI 号的数组，与侦听器将不再接收其更改通知的控件对应。要将此侦听器从已注册侦听器列表中彻底移除，可为 controllers 传递 null。返回的数组包含 MIDI 控件号，侦听器将从现在开始接收其事件。如果侦听器将不接收任何控件的更改通知，则数组长度为 0。

参数：

listener - 旧的侦听器

controllers - 应为其取消更改通知的 MIDI 控件号，或者为 null 以取消所有的控件

返回：

其更改现在将报告给指定侦听器的所有 MIDI 控件号

另请参见：

addControllerEventListener(javax.sound.midi.ControllerEventListener, int[])

setLoopStartPoint

void setLoopStartPoint(long tick)

设置在循环中播放的第一个 MIDI 节拍。如果循环数大于 0，则回放到达循环终点时将跳转到此点。

起始点的值为 0 表示已加载 sequence 的开始。起始点必须小于或等于结束点，并且必须位于已加载 sequence 的大小内。

Sequencer 的循环起始点默认为 sequence 的开始。

参数：

tick - 循环的起始位置，以 MIDI 节拍为单位（从零开始）

抛出：

IllegalArgumentException - 如果所请求的循环起始点无法设置，通常是因为位于 sequence 的持续时间之外或起始点在结束点之后

从以下版本开始：

1.5

另请参见：

setLoopEndPoint(long), setLoopCount(int), getLoopStartPoint(), start()

getLoopStartPoint

long getLoopStartPoint()

获得循环的起始位置，以 MIDI 节拍为单位。

返回：

循环的起始位置，以 MIDI 节拍为单位（从零开始）

从以下版本开始：

1.5

另请参见：

setLoopStartPoint(long)

setLoopEndPoint

void setLoopEndPoint(long tick)

设置在循环中播放的最后一个 MIDI 节拍。如果循环数为 0，则循环结束点将无效，回放在到达循环结束点时会继续播放。

结束点值为 -1 指示 sequence 的最后节拍。否则，结束点必须大于或等于起始点，并且必须位于已加载 sequence 的大小内。

Sequencer 的循环结束点默认为 -1，表示 sequence 的结束点。

参数：

tick - 循环的结束位置，以 MIDI 节拍为单位（从零开始），-1 指示结束点节拍

抛出：

IllegalArgumentException - 如果所请求的循环点无法设置，通常是因为位于 sequence 的持续时间之外或结束点在起始点之前

从以下版本开始：

1.5

另请参见：

setLoopStartPoint(long), setLoopCount(int), getLoopEndPoint(), start()

getLoopEndPoint

long getLoopEndPoint()

获得循环的结束位置，以 MIDI 节拍为单位。

返回：

循环的结束位置，以 MIDI 节拍为单位（从零开始），-1 指示 sequence 的结束点

从以下版本开始：

1.5

另请参见：

setLoopEndPoint(long)

setLoopCount

void setLoopCount(int count)

设置循环回放的重复次数。当回放位置到达循环结束点时，它将返回到循环起始点 count 次，此后回放将继续播放，直到 sequence 的结束点为止。

如果此方法调用时，当前位置大于循环结束点，则回放会继续进行至 sequence 的结束点而不循环，除非随后更改了循环结束点。

count 值为 0 可禁用循环：回放将在循环结束点继续，不会返回到循环起始点。这是 sequencer 的默认方式。

如果回放在循环时停止，则当前循环状态被清除；后续开始请求不受已中断循环操作的影响。

参数：

count - 回放应从循环结束点返回循环起始点的次数，或 LOOP_CONTINUOUSLY 指示循环应一直继续直到被中断

抛出：

IllegalArgumentException - 如果 count 为负且不等于 LOOP_CONTINUOUSLY

从以下版本开始：

1.5

另请参见：

setLoopStartPoint(long), setLoopEndPoint(long), getLoopCount(), start()

getLoopCount

int getLoopCount()

获得回放的重复次数。

返回：

回放在其播放至 sequence 结束点后的循环数

从以下版本开始：

1.5

另请参见：

setLoopCount(int), start()

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。