模块 java.desktop
包 javax.sound.midi

接口 Sequencer

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

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

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

  • 字段详细信息

    • LOOP_CONTINUOUSLY

      static final int LOOP_CONTINUOUSLY
      一个值，表示循环应无限期地继续，而不是在特定数量的循环后完成。
      自从：
      1.5
      参见：

  • 方法详情

    • 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 开始运行。 isRunning 然后返回 true，直到序列播放完成或调用 stop() 。
      返回：
      true 如果 Sequencer 正在运行，否则 false

    • startRecording

      void startRecording()
      开始录制和播放 MIDI 数据。数据被记录到所有启用的轨道，在它们被启用的通道上。录音从音序器的当前位置开始。在录制会话期间，轨道中已有的任何事件都将被重写。来自当前加载序列的事件（如果有的话）与录制期间收到的消息一起传送到音序器的发射器。

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

      抛出：
      IllegalStateException - 如果 Sequencer 关闭
      参见：

    • stopRecording

      void stopRecording()
      停止录制（如果处于活动状态）。继续播放当前序列。
      抛出：
      IllegalStateException - 如果 Sequencer 关闭
      参见：

    • isRecording

      boolean isRecording()
      指示音序器当前是否正在录制。默认值为 false 。 Sequencer 在调用 startRecording() 时开始记录，然后返回 true 直到调用 stop() 或 stopRecording() 。
      返回：
      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)
      按提供的系数缩放音序器的实际播放速度。默认值为 1.0。值 1.0 表示自然速率（序列中指定的速度），2.0 表示快两倍，等等。速度因子不影响 getTempoInMPQ() 和 getTempoInBPM() 返回的值。这些值表示缩放之前的速度。

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

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

    • getTempoFactor

      float getTempoFactor()
      返回音序器的当前速度因子。默认值为 1.0。
      返回：
      节奏因素
      参见：

    • getTickLength

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

    • getTickPosition

      long getTickPosition()
      获取序列中的当前位置，以 MIDI 节拍表示。 （以秒为单位的滴答持续时间由速度和存储在 Sequence 中的计时分辨率决定。）
      返回：
      当前 tick
      参见：

    • setTickPosition

      void setTickPosition(long tick)
      以 MIDI 节拍设置当前音序器位置。
      参数：
      tick - 所需的刻度位置
      参见：

    • getMicrosecondLength

      long getMicrosecondLength()
      获取当前序列的长度，单位为微秒，如果没有设置序列则为0。
      返回：
      序列的长度（以微秒为单位）

    • getMicrosecondPosition

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

    • setMicrosecondPosition

      void setMicrosecondPosition(long microseconds)
      设置序列中的当前位置，以微秒表示。
      参数：
      microseconds - 以微秒为单位的所需位置
      参见：

    • setMasterSyncMode

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

    • getMasterSyncMode

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

    • getMasterSyncModes

      Sequencer.SyncMode [] getMasterSyncModes()
      获得此定序器支持的主同步模式集。
      返回：
      可用的主同步模式
      参见：

    • setSlaveSyncMode

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

    • getSlaveSyncMode

      Sequencer.SyncMode  getSlaveSyncMode()
      获取此定序器的当前从属同步模式。
      返回：
      当前从同步模式
      参见：

    • getSlaveSyncModes

      Sequencer.SyncMode [] getSlaveSyncModes()
      获取sequencer支持的slave同步模式集。
      返回：
      可用的从属同步模式
      参见：

    • 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
      参见：