Module java.desktop
Package javax.sound.sampled

Interface DataLine

所有超接口:
AutoCloseable, Line
所有已知子接口:
Clip, SourceDataLine, TargetDataLine
public interface DataLine extends Line
DataLine为其超接口Line添加了与媒体相关的功能。这些功能包括控制传递到该线路的音频数据的启动、停止、排空和刷新的方法。数据线还可以报告媒体的当前位置、音量和音频格式。数据线用于通过子接口SourceDataLine或Clip的输出来输出音频，这允许应用程序编写数据。类似地，音频输入由子接口TargetDataLine处理，它允许读取数据。

数据线具有内部缓冲区，其中传入或传出的音频数据被排队。drain()方法会阻塞，直到内部缓冲区变空，通常是因为所有排队的数据已被处理。flush()方法会丢弃内部缓冲区中的任何可用排队数据。

数据线在开始或停止主动呈现或捕获数据时会产生START和STOP事件。这些事件可以响应特定请求生成，也可以作为较不直接的状态更改的结果生成。例如，如果在非活动数据线上调用start()，并且有数据可用于捕获或播放，那么当实际开始数据播放或捕获时，将很快生成一个START事件。或者，如果向活动数据线的数据流受限，导致数据呈现中出现间隙，将生成一个STOP事件。

混音器通常支持多个数据线的同步控制。同步可以通过Mixer接口的synchronize方法建立。有关更完整的描述，请参阅Mixer接口的描述。

自 JDK 版本:
1.3
另请参阅:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    DataLine.Info
    除了从其超类继承的类信息外，DataLine.Info还提供了特定于数据线的附加信息。

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    available()
    获取当前可用于应用程序在数据线内部缓冲区中处理的数据字节数。
    void
    drain()
    通过继续数据 I/O 来从线路中排空排队数据，直到数据线的内部缓冲区已被清空。
    void
    flush()
    从线路中刷新排队数据。
    int
    getBufferSize()
    获取将适合于数据线内部缓冲区的最大数据字节数。
    AudioFormat
    getFormat()
    获取数据线音频数据的当前格式（编码、采样率、通道数等）。
    int
    getFramePosition()
    获取音频数据中的当前位置，以采样帧为单位。
    float
    getLevel()
    获取线路的当前音量级别。
    long
    getLongFramePosition()
    获取音频数据中的当前位置，以采样帧为单位。
    long
    getMicrosecondPosition()
    获取音频数据中的当前位置，以微秒为单位。
    boolean
    isActive()
    指示线路是否正在进行活动 I/O（如播放或捕获）。
    boolean
    isRunning()
    指示线路是否正在运行。
    void
    start()
    允许线路进行数据 I/O。
    void
    stop()
    停止线路。

    Methods declared in interface javax.sound.sampled.Line

    addLineListener, close, getControl, getControls, getLineInfo, isControlSupported, isOpen, open, removeLineListener

  • Method Details

    • drain

      void drain()
      通过继续数据 I/O 来从线路中排空排队数据，直到数据线的内部缓冲区已被清空。此方法会阻塞，直到排空完成。由于这是一个阻塞方法，应谨慎使用。如果在已停止的线路上调用drain()且其队列中有数据，则该方法将阻塞，直到线路运行并且数据队列变空。如果一个线程调用drain()，而另一个线程继续填充数据队列，则操作将无法完成。当数据线关闭时，此方法总是会返回。
      另请参阅:

    • flush

      void flush()
      刷新线路中的排队数据。刷新的数据将被丢弃。在某些情况下，无法丢弃所有排队数据。例如，混音器可以从特定输入线的缓冲区中刷新数据，但已在输出缓冲区中存在的任何未播放数据（混音的结果）仍将被播放。如果在暂停线路后（正常情况）想要跳过“陈旧”数据以便重新开始播放或捕获，可以调用此方法。（在活动线路上刷新是合法的，但在活动线路上这样做可能会导致数据的不连续，从而产生可察觉的点击声。）
      另请参阅:

    • start

      void start()
      允许线路进行数据 I/O。如果在已运行的线路上调用此方法，则不会执行任何操作。除非缓冲区中的数据已被刷新，否则线路将从停止时未处理的第一帧开始恢复 I/O。当音频捕获或播放开始时，将生成一个START事件。
      另请参阅:

    • stop

      void stop()
      停止线路。已停止的线路应停止 I/O 活动。但是，如果线路是打开且正在运行的，则应保留恢复活动所需的资源。已停止的线路应保留其缓冲区中的任何音频数据，而不是丢弃它，以便在恢复时可以继续 I/O，如果可能的话。（当然，这并不保证当前缓冲区之外永远不会有不连续；如果停止状态持续时间过长，可能会丢弃输入或输出样本。）如果需要，可以通过调用flush方法丢弃保留的数据。当音频捕获或播放停止时，将生成一个STOP事件。
      另请参阅:

    • isRunning

      boolean isRunning()
      指示线路是否正在运行。默认值为false。打开的线路在首次响应start方法调用时呈现第一个数据时开始运行，并在响应stop调用或因播放完成而停止呈现时继续运行。
      返回值:
      如果线路正在运行，则返回true，否则返回false
      另请参阅:

    • isActive

      boolean isActive()
      指示线路是否正在进行活动 I/O（如播放或捕获）。当非活动线路变为活动时，它会向其侦听器发送一个START事件。同样，当活动线路变为非活动时，它会发送一个STOP事件。
      返回值:
      如果线路正在积极地捕获或渲染声音，则返回true，否则返回false
      另请参阅:

    • getFormat

      AudioFormat getFormat()
      获取数据线音频数据的当前格式（编码、采样率、通道数等）。

      如果线路未打开且从未打开过，则返回默认格式。默认格式是特定实现的音频格式，或者如果用于检索此DataLine的DataLine.Info对象指定了至少一个完全限定的音频格式，则最后一个将被用作默认格式。使用特定音频格式（例如SourceDataLine.open(AudioFormat)）打开线路将覆盖默认格式。

      返回值:
      当前音频数据格式
      另请参阅:

    • getBufferSize

      int getBufferSize()
      获取将适合于数据线内部缓冲区的最大数据字节数。对于源数据线，这是可以写入数据的缓冲区的大小。对于目标数据线，这是可以从中读取数据的缓冲区的大小。请注意，使用的单位是字节，但始终对应于音频数据的整数帧数。
      返回值:
      缓冲区的大小，以字节为单位

    • available

      int available()
      获取当前可用于应用程序在数据线内部缓冲区中处理的数据字节数。对于源数据线，这是可以写入缓冲区而不会阻塞的数据量。对于目标数据线，这是应用程序可以读取的数据量。对于剪辑，此值始终为0，因为音频数据在剪辑打开时加载到缓冲区中，并且在剪辑关闭之前保持不变。

      请注意，使用的单位是字节，但始终对应于音频数据样本帧的整数数量。

      应用程序保证从available()返回的字节数进行读取或写入操作不会阻塞；但是，不能保证尝试读取或写入更多数据会阻塞。

      返回：
      可用数据量，以字节为单位

    • getFramePosition

      int getFramePosition()
      获取音频数据中的当前位置，以样本帧为单位。帧位置测量自打开以来由线路捕获或渲染的样本帧数量。此返回值在2^31帧后会循环。建议改用getLongFramePosition。
      返回：
      自打开线路以来已处理的帧数
      另请参见：

    • getLongFramePosition

      long getLongFramePosition()
      获取音频数据中的当前位置，以样本帧为单位。帧位置测量自打开以来由线路捕获或渲染的样本帧数量。
      返回：
      自打开线路以来已处理的帧数
      自1.5版本起：
      1.5

    • getMicrosecondPosition

      long getMicrosecondPosition()
      获取音频数据中的当前位置，以微秒为单位。微秒位置测量自打开以来由线路捕获或渲染的样本帧数量所对应的时间。精度水平不受保证。例如，实现可能会根据当前帧位置和音频样本帧速率计算微秒位置。然后，微秒的精度将受限于每个样本帧的微秒数。
      返回：
      自打开线路以来已处理的数据的微秒数

    • getLevel

      float getLevel()
      获取线路的当前音量级别。此级别是信号当前振幅的度量，不应与增益控制的当前设置混淆。范围从0.0（静音）到1.0（声波的最大可能振幅）。单位为线性振幅，而不是分贝。
      返回：
      此线路中信号的当前振幅，或AudioSystem.NOT_SPECIFIED