Module java.desktop
Package javax.sound.midi

Interface Sequencer

所有超接口:
AutoCloseable, MidiDevice
public interface Sequencer extends MidiDevice
播放 MIDI sequence 的硬件或软件设备称为序列器。MIDI 序列包含时间戳 MIDI 数据的列表，例如可以从标准 MIDI 文件中读取的数据。大多数序列器还提供用于创建和编辑序列的功能。

Sequencer 接口包括以下基本 MIDI 序列器操作的方法：

  • 从 MIDI 文件数据获取序列
  • 开始和停止播放
  • 移动到序列中的任意位置
  • 更改播放速度（速度）
  • 将播放与内部时钟或接收到的 MIDI 消息同步
  • 控制另一个设备的定时
此外，以下操作受支持，可以直接或间接通过Sequencer可以访问的对象进行：
  • 通过添加或删除单个 MIDI 事件或整个轨道来编辑数据
  • 静音或独奏序列中的单个轨道
  • 在播放序列时通知监听器对象遇到的任何元事件或控制变化事件
参见:

  • Field Details

    • LOOP_CONTINUOUSLY

      static final int LOOP_CONTINUOUSLY
      表示循环应该无限继续而不是在特定循环次数后完成。
      自 JDK 版本:
      1.5
      参见:

  • Method Details

    • setSequence

      void setSequence(Sequence sequence) throws InvalidMidiDataException
      设置序列器当前操作的当前序列。

      即使Sequencer已关闭，也可以调用此方法。

      参数:
      sequence - 要加载的序列
      抛出:
      InvalidMidiDataException - 如果序列包含无效的 MIDI 数据，或不受支持

    • setSequence

      void setSequence(InputStream stream) throws IOException, InvalidMidiDataException
      设置序列器当前操作的当前序列。流必须指向 MIDI 文件数据。

      即使Sequencer已关闭，也可以调用此方法。

      参数:
      stream - 包含 MIDI 文件数据的流
      抛出:
      IOException - 如果在读取流时发生 I/O 异常
      InvalidMidiDataException - 如果在流中遇到无效数据，或流不受支持

    • getSequence

      Sequence getSequence()
      获取 Sequencer 当前操作的序列。

      即使Sequencer已关闭，也可以调用此方法。

      返回:
      当前序列，如果当前未设置序列则返回null

    • start

      void start()
      开始播放当前加载的序列中的 MIDI 数据。播放将从当前位置开始。如果播放位置达到循环结束点，并且循环计数大于 0，则播放将在使用setLoopCount设置的重复次数后恢复到循环开始点。之后，或者如果循环计数为 0，则播放将继续播放到序列的结尾。

      实现确保在跳转到循环开始点时将合成器带到一致状态，通过发送适当的控制器、音高弯曲和程序更改事件。

      抛出:
      IllegalStateException - 如果Sequencer已关闭
      参见:

    • stop

      void stop()
      停止录制（如果活动），以及当前加载的序列的播放（如果有）。
      抛出:
      IllegalStateException - 如果Sequencer已关闭
      参见:

    • isRunning

      boolean isRunning()
      指示 Sequencer 当前是否正在运行。默认为false。当调用start()或startRecording()时，Sequencer 开始运行。然后，直到播放序列完成或调用stop()，isRunning将返回true。
      返回:
      如果 Sequencer 正在运行，则返回true，否则返回false

    • startRecording

      void startRecording()
      开始录制和播放 MIDI 数据。数据将记录到所有已启用的轨道，对于启用了的通道，数据将记录到这些通道上。录制从序列器的当前位置开始。已在轨道中的任何事件将在录制会话的持续时间内被覆盖。当前加载的序列（如果有）的事件将与录制期间接收到的消息一起传递到序列器的发射器。

      请注意，默认情况下，轨道未启用录制。为了录制 MIDI 数据，至少必须专门启用一个轨道以进行录制。

      抛出:
      IllegalStateException - 如果Sequencer已关闭
      参见:

    • stopRecording

      void stopRecording()
      停止录制，如果正在进行中。当前序列的播放将继续。
      抛出:
      IllegalStateException - 如果Sequencer已关闭
      参见:

    • isRecording

      boolean isRecording()
      指示Sequencer当前是否正在录制。默认值为false。当调用startRecording()时，Sequencer开始录制，然后在调用stop()或stopRecording()之前返回true。
      返回:
      如果Sequencer正在录制，则为true，否则为false

    • recordEnable

      void recordEnable(Track track, int channel)
      为接收特定通道上的事件而准备指定的轨道进行录制。一旦启用，当录制处于活动状态时，轨道将接收事件。
      参数:
      track - 将记录事件的轨道
      channel - 将接收事件的通道。如果通道值为-1，则轨道将接收来自所有通道的数据。
      抛出:
      IllegalArgumentException - 如果轨道不是当前序列的一部分

    • recordDisable

      void recordDisable(Track track)
      禁用对指定轨道的录制。事件将不再记录到此轨道中。
      参数:
      track - 要禁用录制的轨道，或null以禁用所有轨道的录制

    • getTempoInBPM

      float getTempoInBPM()
      获取当前的速度，以每分钟节拍数表示。播放速度的实际速度是返回值和速度因子的乘积。
      返回:
      每分钟节拍数的当前速度
      参见:

    • setTempoInBPM

      void setTempoInBPM(float bpm)
      设置每分钟的速度。播放速度的实际速度是指定值和速度因子的乘积。
      参数:
      bpm - 每分钟的新速度
      参见:

    • getTempoInMPQ

      float getTempoInMPQ()
      获取当前的速度，以每四分音符的微秒数表示。播放速度的实际速度是返回值和速度因子的乘积。
      返回:
      每四分音符的当前速度的微秒数
      参见:

    • setTempoInMPQ

      void setTempoInMPQ(float mpq)
      设置每四分音符的速度。播放速度的实际速度是指定值和速度因子的乘积。
      参数:
      mpq - 每四分音符的新速度的微秒数
      参见:

    • setTempoFactor

      void setTempoFactor(float factor)
      通过提供的因子调整Sequencer的实际播放速度。默认值为1.0。值为1.0表示自然速率（序列中指定的速度），2.0表示两倍速，依此类推。速度因子不会影响getTempoInMPQ()和getTempoInBPM()返回的值。这些值表示缩放之前的速度。

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

      参数:
      factor - 请求的速度标量
      参见:

    • getTempoFactor

      float getTempoFactor()
      返回Sequencer的当前速度因子。默认值为1.0。
      返回:
      速度因子
      参见:

    • getTickLength

      long getTickLength()
      获取当前序列的长度，以MIDI滴答表示，如果未设置序列则为0。
      返回:
      滴答中序列的长度

    • getTickPosition

      long getTickPosition()
      获取当前序列中的位置，以MIDI滴答表示。 （滴答的持续时间由速度和存储在Sequence中的时间分辨率共同确定。）
      返回:
      当前滴答
      参见:

    • setTickPosition

      void setTickPosition(long tick)
      设置MIDI滴答中的当前Sequencer位置。
      参数:
      tick - 所需的滴答位置
      参见:

    • getMicrosecondLength

      long getMicrosecondLength()
      获取当前序列的长度，以微秒表示，如果未设置序列则为0。
      返回:
      微秒中序列的长度

    • getMicrosecondPosition

      long getMicrosecondPosition()
      获取当前序列中的位置，以微秒表示。
      指定者:
      getMicrosecondPosition 在接口 MidiDevice
      返回:
      微秒中的当前位置
      参见:

    • setMicrosecondPosition

      void setMicrosecondPosition(long microseconds)
      设置当前位置，以微秒表示。
      参数:
      microseconds - 期望的微秒位置
      参见:

    • setMasterSyncMode

      void setMasterSyncMode(Sequencer.SyncMode sync)
      设置此Sequencer使用的时间信息源。Sequencer与主时钟同步，主时钟可以是内部时钟、MIDI时钟或MIDI时间码，具体取决于sync的值。 sync参数必须是由getMasterSyncModes()返回的受支持模式之一。
      参数:
      sync - 所需的主同步模式
      参见:

    • getMasterSyncMode

      Sequencer.SyncMode getMasterSyncMode()
      获取此Sequencer的当前主同步模式。
      返回:
      当前主同步模式
      参见:

    • getMasterSyncModes

      Sequencer.SyncMode[] getMasterSyncModes()
      获取此Sequencer支持的主同步模式集。
      返回:
      可用的主同步模式
      参见:

    • setSlaveSyncMode

      void setSlaveSyncMode(Sequencer.SyncMode sync)
      设置此Sequencer的从属同步模式。这指示Sequencer向其接收器发送的时间信息类型。 sync参数必须是由getSlaveSyncModes()返回的受支持模式之一。
      参数:
      sync - 所需的从属同步模式
      参见:

    • getSlaveSyncMode

      Sequencer.SyncMode getSlaveSyncMode()
      获取此Sequencer的当前从属同步模式。
      返回值:
      当前从属同步模式
      参见:

    • getSlaveSyncModes

      Sequencer.SyncMode[] getSlaveSyncModes()
      获取序列器支持的从属同步模式集合。
      返回值:
      可用的从属同步模式
      参见:

    • setTrackMute

      void setTrackMute(int track, boolean mute)
      设置轨道的静音状态。此方法可能因多种原因而失败。例如，指定的轨道号可能对当前序列无效，或者序列器可能不支持此功能。需要验证此操作是否成功的应用程序应在此调用后调用getTrackMute(int)。
      参数:
      track - 轨道号。当前序列中的轨道编号从0到序列中轨道数减1。
      mute - 轨道的新静音状态。 true 表示应该静音轨道，false 表示应该取消静音轨道。
      参见:

    • getTrackMute

      boolean getTrackMute(int track)
      获取轨道的当前静音状态。所有未静音的轨道的默认静音状态为false。如果指定的轨道未被静音，则此方法应返回false。这适用于序列器不支持轨道静音，以及指定的轨道索引无效的情况。
      参数:
      track - 轨道号。当前序列中的轨道编号从0到序列中轨道数减1。
      返回值:
      如果静音则为true，如果未静音则为false

    • setTrackSolo

      void setTrackSolo(int track, boolean solo)
      设置轨道的独奏状态。如果solo为true，则只有此轨道和其他独奏的轨道会发声。如果solo为false，则只有其他独奏的轨道会发声，除非没有轨道被独奏，此时所有未静音的轨道会发声。

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

      参数:
      track - 轨道号。当前序列中的轨道编号从0到序列中轨道数减1。
      solo - 轨道的新独奏状态。 true 表示应该独奏轨道，false 表示应该取消独奏轨道。
      参见:

    • getTrackSolo

      boolean getTrackSolo(int track)
      获取轨道的当前独奏状态。所有未独奏的轨道的默认独奏状态为false。如果指定的轨道未被独奏，则此方法应返回false。这适用于序列器不支持轨道独奏，以及指定的轨道索引无效的情况。
      参数:
      track - 轨道号。当前序列中的轨道编号从0到序列中轨道数减1。
      返回值:
      如果独奏则为true，如果未独奏则为false

    • addMetaEventListener

      boolean addMetaEventListener(MetaEventListener listener)
      注册元事件监听器，以便在序列中遇到元事件并由序列器处理时接收通知。如果例如，此类序列器不支持元事件通知，则此方法可能失败。
      参数:
      listener - 要添加的监听器
      返回值:
      如果成功添加监听器则为true，否则为false
      参见:

    • removeMetaEventListener

      void removeMetaEventListener(MetaEventListener listener)
      从此序列器的已注册监听器列表中移除指定的元事件监听器，如果实际上该监听器已注册。
      参数:
      listener - 要移除的元事件监听器
      参见:

    • addControllerEventListener

      int[] addControllerEventListener(ControllerEventListener listener, int[] controllers)
      注册控制器事件监听器，以便在序列器处理请求类型或类型的控制器事件时接收通知。类型由controllers参数指定，该参数应包含一个MIDI控制器编号的数组。（每个编号应在0到127之间，包括0和127。有关对应于各种控制器类型的编号，请参阅MIDI 1.0规范。）

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

      参数:
      listener - 要添加到已注册监听器列表中的控制器事件监听器
      controllers - 请求更改通知的MIDI控制器编号
      返回值:
      现在将向指定监听器报告所有MIDI控制器的编号
      参见:

    • removeControllerEventListener

      int[] removeControllerEventListener(ControllerEventListener listener, int[] controllers)
      移除控制器事件监听器对一个或多个类型的控制器事件的兴趣。 controllers参数是一个与控制器对应的MIDI编号数组，表示监听器不再接收更改通知的控制器。要完全从已注册监听器列表中删除此监听器，请为controllers传入null。返回的数组包含现在监听器将接收事件的MIDI控制器编号。如果监听器不会接收任何控制器的更改通知，则数组的长度为0。
      参数:
      listener - 旧监听器
      controllers - 应取消更改通知的MIDI控制器编号，或者为所有控制器取消传入null
      返回值:
      现在将向指定监听器报告所有MIDI控制器的编号
      参见:

    • setLoopStartPoint

      void setLoopStartPoint(long tick)
      设置将在循环中播放的第一个MIDI滴答。如果循环计数大于0，则在达到循环结束点时播放将跳转到此点。

      起始点为0表示加载序列的开头。起始点必须小于或等于结束点，并且必须落在加载序列的范围内。

      序列器的循环起始点默认为序列的开头。

      参数:
      tick - 循环的起始位置，以MIDI滴答为单位（从零开始）
      抛出:
      IllegalArgumentException - 如果无法设置请求的循环起始点，通常是因为它超出了序列的持续时间或因为起始点在结束点之后
      自:
      1.5
      参见:

    • getLoopStartPoint

      long getLoopStartPoint()
      获取循环的开始位置，以MIDI滴答为单位。
      返回值:
      循环的开始位置，以MIDI滴答为单位（从零开始）
      自:
      1.5
      参见:

    • setLoopEndPoint

      void setLoopEndPoint(long tick)
      设置将在循环中播放的最后一个MIDI滴答。如果循环计数为0，则循环结束点不起作用，播放将继续播放到达循环结束点时。

      结束点为-1表示序列的最后一个滴答。否则，结束点必须大于或等于起始点，并且必须落在加载序列的范围内。

      序列器的循环结束点默认为-1，表示序列的结尾。

      参数:
      tick - 循环的结束位置，以MIDI滴答数（从零开始）表示，或者为-1表示最终滴答数
      抛出:
      IllegalArgumentException - 如果无法设置请求的循环点，通常是因为超出了序列的持续时间或者结束点在起始点之前
      自版本:
      1.5
      另请参阅:

    • getLoopEndPoint

      long getLoopEndPoint()
      获取循环的结束位置，以MIDI滴答数表示。
      返回:
      循环的结束位置，以MIDI滴答数（从零开始）表示，或者为-1表示序列的结束
      自版本:
      1.5
      另请参阅:

    • setLoopCount

      void setLoopCount(int count)
      设置循环播放的重复次数。当播放位置达到循环结束点时，它将循环返回到循环起始点count次，之后播放将继续播放到序列的结束。

      如果在调用此方法时的当前位置大于循环结束点，则播放将继续到序列的结束而不会循环，除非后续更改了循环结束点。

      count值为0将禁用循环：播放将继续到循环结束点，而不会循环回到循环起始点。这是一个序列器的默认设置。

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

      参数:
      count - 播放应该从循环的结束位置回到循环的起始位置的次数，或者LOOP_CONTINUOUSLY表示循环应该持续直到中断
      抛出:
      IllegalArgumentException - 如果count为负且不等于LOOP_CONTINUOUSLY
      自版本:
      1.5
      另请参阅:

    • getLoopCount

      int getLoopCount()
      获取播放的重复次数。
      返回:
      播放到序列结束后的循环次数
      自版本:
      1.5
      另请参阅: