模块 java.desktop
包 javax.sound.sampled

类 AudioSystem

java.lang.Object
javax.sound.sampled.AudioSystem
public class AudioSystem extends Object
AudioSystem 类充当采样音频系统资源的入口点。此类允许您查询和访问系统上安装的混音器。 AudioSystem 包括许多用于在不同格式之间转换音频数据以及在音频文件和流之间进行转换的方法。它还提供了一种直接从 AudioSystem 获取 Line 的方法，而无需显式处理混频器。

属性可用于指定特定线型的默认混合器。系统属性和属性文件都被考虑在内。 “sound.properties”属性文件是从特定于实现的位置（通常是 Java 安装目录中的 conf 目录）读取的。可选的“javax.sound.config.file”系统属性可用于指定将作为初始配置读取的属性文件。如果某个属性既作为系统属性又存在于属性文件中，则系统属性优先。如果未指定，则会在可用设备中选择合适的默认值。 Properties.load 中指定了属性文件的语法。下表列出了可用的属性键以及考虑它们的方法：

音频系统属性键
属性键 接口 受影响的方法
javax.sound.sampled.Clip Clip getLine(javax.sound.sampled.Line.Info) , getClip()
javax.sound.sampled.Port Port getLine(javax.sound.sampled.Line.Info)
javax.sound.sampled.SourceDataLine SourceDataLine getLine(javax.sound.sampled.Line.Info) , getSourceDataLine(javax.sound.sampled.AudioFormat)
javax.sound.sampled.TargetDataLine TargetDataLine getLine(javax.sound.sampled.Line.Info) , getTargetDataLine(javax.sound.sampled.AudioFormat)
属性值由提供者类名和混合器名组成，由井号（“#”）分隔。提供程序类名称是具体 mixer provider 类的完全限定名称。混音器名称与 Mixer.Info 的 getName 方法返回的 String 匹配。可以省略类名或混音器名称。如果仅指定了类名，则尾随散列标记是可选的。

如果指定了提供程序类，并且可以从已安装的提供程序中成功检索到它，则会从提供程序中检索 Mixer.Info 对象列表。否则，或者当这些混合器不提供后续匹配时，将从 getMixerInfo() 检索列表以包含所有可用的 Mixer.Info 对象。

如果指定了混音器名称，则会搜索 Mixer.Info 对象的结果列表：将返回第一个具有匹配名称且其 Mixer 提供相应线路接口的对象。如果未找到匹配的 Mixer.Info 对象，或者未指定混音器名称，则将返回结果列表中提供相应线路接口的第一个混音器。

例如，当调用 getLine 请求 Clip 实例时，值为 "com.sun.media.sound.MixerProvider#SunClip" 的属性 javax.sound.sampled.Clip 将产生以下结果：如果类 com.sun.media.sound.MixerProvider 存在于已安装的混合器提供程序列表中，则将返回第一个名为 "SunClip" 的混合器的第一个 Clip .如果找不到，将返回指定提供者的第一个混音器的第一个Clip，而不考虑名称。如果没有，则返回所有混频器列表中名称为"SunClip"的第一个Mixer的第一个Clip（由getMixerInfo返回），或者，如果未找到，则返回可以在返回所有混音器的列表。如果同样失败，则会抛出 IllegalArgumentException。

自从：
1.3
参见：

  • 字段详细信息

    • NOT_SPECIFIED

      public static final int NOT_SPECIFIED
      代表未知数值的整数。此值仅适用于通常不取负值的有符号数量。示例包括文件大小、帧大小、缓冲区大小和采样率。许多 Java Sound 构造函数接受此类参数的值 NOT_SPECIFIED。如文档所述，其他方法也可以接受或返回此值。
      参见：

  • 方法详情

    • getMixerInfo

      public static Mixer.Info [] getMixerInfo()
      获取一组混合器信息对象，这些对象表示系统上当前安装的一组音频混合器。
      返回：
      当前安装的混音器的一组信息对象。如果系统上没有可用的混音器，则返回一个长度为 0 的数组。
      参见：

    • getMixer

      public static Mixer  getMixer(Mixer.Info  info)
      获取请求的混音器。
      参数：
      info - 代表所需混频器的 Mixer.Info 对象，或代表系统默认混频器的 null
      返回：
      请求的混频器
      抛出：
      SecurityException - 如果由于安全限制请求的混音器不可用
      IllegalArgumentException - 如果信息对象不代表系统上安装的混音器
      参见：

    • getSourceLineInfo

      public static Line.Info [] getSourceLineInfo(Line.Info  info)
      获取有关已安装混音器支持的特定类型的所有源代码行的信息。
      参数：
      info - 一个 Line.Info 对象，指定请求信息的行类型
      返回：
      一个 Line.Info 对象数组，描述与请求类型匹配的源代码行。如果不支持匹配的源代码行，则返回一个长度为 0 的数组。
      参见：

    • getTargetLineInfo

      public static Line.Info [] getTargetLineInfo(Line.Info  info)
      获取有关已安装的混合器支持的特定类型的所有目标行的信息。
      参数：
      info - 一个 Line.Info 对象，指定请求信息的行类型
      返回：
      Line.Info 对象数组，描述匹配请求类型的目标行。如果不支持匹配的目标行，则返回一个长度为 0 的数组。
      参见：

    • isLineSupported

      public static boolean isLineSupported(Line.Info  info)
      指示系统是否支持与指定的 Line.Info 对象匹配的任何行。如果任何已安装的混音器支持一条线，则支持该线。
      参数：
      info - 一个 Line.Info 对象，描述查询支持的行
      返回：
      true 如果至少支持一个匹配行，否则 false
      参见：

    • getLine

      public static Line  getLine(Line.Info  info) throws LineUnavailableException
      获取与指定 Line.Info 对象中的描述相匹配的行。

      如果请求 DataLine，并且 info 是 DataLine.Info 的实例，指定至少一种完全合格的音频格式，最后一个将用作返回的 DataLine 的默认格式。

      如果定义了系统属性 javax.sound.sampled.Clip 、 javax.sound.sampled.Port 、 javax.sound.sampled.SourceDataLine 和 javax.sound.sampled.TargetDataLine 或它们在文件“sound.properties”中定义，则它们用于检索默认行。有关详细信息，请参阅 class description 。如果未设置相应的属性，或者属性中请求的混频器未安装或未提供请求的线路，则将查询所有已安装的混频器以获取请求的线路类型。 Line 将从提供请求的线路类型的第一个混频器返回。

      参数：
      info - 一个 Line.Info 对象，描述所需的线类型
      返回：
      请求类型的一行
      抛出：
      LineUnavailableException - 如果匹配行由于资源限制不可用
      SecurityException - 如果匹配行由于安全限制不可用
      IllegalArgumentException - 如果系统不支持通过任何已安装的混合器匹配指定的 Line.Info 对象的至少一行

    • getClip

      public static Clip  getClip() throws LineUnavailableException
      获取可用于播放音频文件或音频流的剪辑。返回的剪辑将由默认系统混音器提供，或者，如果不可能，则由系统中安装的支持 Clip 对象的任何其他混音器提供。

      必须使用 open(AudioFormat) 或 open(AudioInputStream) 方法打开返回的剪辑。

      这是一个在内部使用 getMixer 和 getLine 的高级方法。

      如果系统属性 javax.sound.sampled.Clip 已定义或在文件“sound.properties”中定义，则用于检索默认剪辑。有关详细信息，请参阅 class description 。

      返回：
      所需的剪辑对象
      抛出：
      LineUnavailableException - 如果由于资源限制剪辑对象不可用
      SecurityException - 如果剪辑对象由于安全限制不可用
      IllegalArgumentException - 如果系统不支持通过任何已安装的混音器的至少一个剪辑实例
      自从：
      1.5
      参见：

    • getClip

      public static Clip  getClip(Mixer.Info  mixerInfo) throws LineUnavailableException
      从指定混音器中获取可用于播放音频文件或音频流的剪辑。

      必须使用 open(AudioFormat) 或 open(AudioInputStream) 方法打开返回的剪辑。

      这是一个在内部使用 getMixer 和 getLine 的高级方法。

      参数：
      mixerInfo - 代表所需混频器的 Mixer.Info 对象，或代表系统默认混频器的 null
      返回：
      来自指定混音器的剪辑对象
      抛出：
      LineUnavailableException - 如果由于资源限制无法从该混音器中获得剪辑
      SecurityException - 如果由于安全限制无法从该混音器中获得剪辑
      IllegalArgumentException - 如果系统不支持至少一个剪辑通过指定的混音器
      自从：
      1.5
      参见：

    • getSourceDataLine

      public static SourceDataLine  getSourceDataLine(AudioFormat  format) throws LineUnavailableException
      获取可用于播放AudioFormat对象指定格式的音频数据的源数据线。返回的行将由默认系统混音器提供，或者，如果不可能，则由系统中安装的支持匹配 SourceDataLine 对象的任何其他混音器提供。

      应使用 open(AudioFormat) 或 open(AudioFormat, int) 方法打开返回的行。

      这是一个在内部使用 getMixer 和 getLine 的高级方法。

      返回的 SourceDataLine 的默认音频格式将使用 format 进行初始化。

      如果系统属性 javax.sound.sampled.SourceDataLine 已定义或在文件“sound.properties”中定义，则用于检索默认源数据行。有关详细信息，请参阅 class description 。

      参数：
      format - 一个 AudioFormat 对象指定返回行支持的音频格式，或 null 用于任何音频格式
      返回：
      所需的 SourceDataLine 对象
      抛出：
      LineUnavailableException - 如果匹配的源数据行由于资源限制不可用
      SecurityException - 如果匹配的源数据行由于安全限制不可用
      IllegalArgumentException - 如果系统不支持通过任何已安装的混音器支持指定音频格式的至少一条源数据线
      自从：
      1.5
      参见：

    • getSourceDataLine

      public static SourceDataLine  getSourceDataLine(AudioFormat  format, Mixer.Info  mixerinfo) throws LineUnavailableException
      获取源数据线，可用于播放由Mixer.Info对象指定的混音器提供的AudioFormat对象指定格式的音频数据。

      应使用 open(AudioFormat) 或 open(AudioFormat, int) 方法打开返回的行。

      这是一个在内部使用 getMixer 和 getLine 的高级方法。

      返回的 SourceDataLine 的默认音频格式将使用 format 进行初始化。

      参数：
      format - 一个 AudioFormat 对象指定返回行支持的音频格式，或 null 用于任何音频格式
      mixerinfo - 代表所需混音器的 Mixer.Info 对象，或代表系统默认混音器的 null
      返回：
      所需的 SourceDataLine 对象
      抛出：
      LineUnavailableException - 如果由于资源限制，指定混音器无法提供匹配的源数据线
      SecurityException - 如果由于安全限制，匹配的源数据线无法从指定的混音器中使用
      IllegalArgumentException - 如果指定的混音器不支持至少一条支持指定音频格式的源数据线
      自从：
      1.5
      参见：

    • getTargetDataLine

      public static TargetDataLine  getTargetDataLine(AudioFormat  format) throws LineUnavailableException
      获取目标数据线，可用于以 AudioFormat 对象指定的格式录制音频数据。返回的行将由默认系统混音器提供，或者，如果不可能，则由系统中安装的支持匹配 TargetDataLine 对象的任何其他混音器提供。

      应使用 open(AudioFormat) 或 open(AudioFormat, int) 方法打开返回的行。

      这是一个在内部使用 getMixer 和 getLine 的高级方法。

      返回的 TargetDataLine 的默认音频格式将使用 format 进行初始化。

      如果系统属性 javax.sound.sampled.TargetDataLine 已定义或在文件“sound.properties”中定义，则用于检索默认目标数据行。有关详细信息，请参阅 class description 。

      参数：
      format - 一个 AudioFormat 对象指定返回行支持的音频格式，或 null 用于任何音频格式
      返回：
      所需的 TargetDataLine 对象
      抛出：
      LineUnavailableException - 如果匹配的目标数据行由于资源限制不可用
      SecurityException - 如果匹配的目标数据行由于安全限制不可用
      IllegalArgumentException - 如果系统不支持至少一条目标数据线通过任何已安装的混音器支持指定的音频格式
      自从：
      1.5
      参见：

    • getTargetDataLine

      public static TargetDataLine  getTargetDataLine(AudioFormat  format, Mixer.Info  mixerinfo) throws LineUnavailableException
      获取目标数据线，可用于以AudioFormat对象指定的格式录制音频数据，由Mixer.Info对象指定的混音器提供。

      应使用 open(AudioFormat) 或 open(AudioFormat, int) 方法打开返回的行。

      这是一个在内部使用 getMixer 和 getLine 的高级方法。

      返回的 TargetDataLine 的默认音频格式将使用 format 进行初始化。

      参数：
      format - 一个 AudioFormat 对象指定返回行支持的音频格式，或 null 用于任何音频格式
      mixerinfo - 代表所需混音器的 Mixer.Info 对象，或代表系统默认混音器的 null
      返回：
      所需的 TargetDataLine 对象
      抛出：
      LineUnavailableException - 如果由于资源限制，匹配的目标数据线无法从指定的混频器获得
      SecurityException - 如果匹配的目标数据线由于安全限制无法从指定的混音器中使用
      IllegalArgumentException - 如果指定的混音器不支持至少一条支持指定音频格式的目标数据线
      自从：
      1.5
      参见：

    • getTargetEncodings

      public static AudioFormat.Encoding [] getTargetEncodings(AudioFormat.Encoding  sourceEncoding)
      获取系统可以使用一组已安装的格式转换器从具有指定编码的音频输入流中获取的编码。
      参数：
      sourceEncoding - 查询转换支持的编码
      返回：
      编码数组。如果不支持 sourceEncoding，则返回一个长度为 0 的数组。否则，数组的长度至少为 1，表示 sourceEncoding（无转换）。
      抛出：
      NullPointerException - 如果 sourceEncoding 是 null

    • getTargetEncodings

      public static AudioFormat.Encoding [] getTargetEncodings(AudioFormat  sourceFormat)
      获取系统可以使用一组已安装的格式转换器从具有指定格式的音频输入流中获取的编码。
      参数：
      sourceFormat - 查询转换的音频格式
      返回：
      编码数组。如果不支持 sourceFormat，则返回长度为 0 的数组。否则，数组的长度至少为1，代表sourceFormat的编码（不转换）。
      抛出：
      NullPointerException - 如果 sourceFormat 是 null

    • isConversionSupported

      public static boolean isConversionSupported(AudioFormat.Encoding  targetEncoding, AudioFormat  sourceFormat)
      指示是否可以从具有指定格式的音频输入流中获取指定编码的音频输入流。
      参数：
      targetEncoding - 转换后所需的编码
      sourceFormat - 转换前的音频格式
      返回：
      true 如果支持转换，否则 false
      抛出：
      NullPointerException - 如果 targetEncoding 或 sourceFormat 是 null

    • getAudioInputStream

      public static AudioInputStream  getAudioInputStream(AudioFormat.Encoding  targetEncoding, AudioInputStream  sourceStream)
      通过转换提供的音频输入流，获得指定编码的音频输入流。
      参数：
      targetEncoding - 转换后所需的编码
      sourceStream - 要转换的流
      返回：
      指定编码的音频输入流
      抛出：
      IllegalArgumentException - 如果不支持转换
      NullPointerException - 如果 targetEncoding 或 sourceStream 是 null
      参见：

    • getTargetFormats

      public static AudioFormat [] getTargetFormats(AudioFormat.Encoding  targetEncoding, AudioFormat  sourceFormat)
      获取具有特定编码的格式，并且系统可以使用一组已安装的格式转换器从指定格式的流中获取这些格式。
      参数：
      targetEncoding - 转换后所需的编码
      sourceFormat - 转换前的音频格式
      返回：
      格式数组。如果不支持指定编码的格式，则返回一个长度为 0 的数组。
      抛出：
      NullPointerException - 如果 targetEncoding 或 sourceFormat 是 null

    • isConversionSupported

      public static boolean isConversionSupported(AudioFormat  targetFormat, AudioFormat  sourceFormat)
      指示是否可以从另一种指定格式的音频输入流中获取指定格式的音频输入流。
      参数：
      targetFormat - 转换后所需的音频格式
      sourceFormat - 转换前的音频格式
      返回：
      true 如果支持转换，否则 false
      抛出：
      NullPointerException - 如果 targetFormat 或 sourceFormat 是 null

    • getAudioInputStream

      public static AudioInputStream  getAudioInputStream(AudioFormat  targetFormat, AudioInputStream  sourceStream)
      通过转换提供的音频输入流，获得指定格式的音频输入流。
      参数：
      targetFormat - 转换后所需的音频格式
      sourceStream - 要转换的流
      返回：
      指定格式的音频输入流
      抛出：
      IllegalArgumentException - 如果不支持转换
      NullPointerException - 如果 targetFormat 或 sourceStream 是 null
      参见：

    • getAudioFileFormat

      public static AudioFileFormat  getAudioFileFormat(InputStream  stream) throws UnsupportedAudioFileException , IOException
      获取提供的输入流的音频文件格式。流必须指向有效的音频文件数据。此方法的实现可能需要多个解析器来检查流以确定它们是否支持它。这些解析器必须能够标记流，读取足够的数据以确定它们是否支持流，并将流的读取指针重置到其原始位置。如果输入流不支持这些操作，此方法可能会失败并返回 IOException 。
      参数：
      stream - 应从中提取文件格式信息的输入流
      返回：
      描述流的音频文件格式的 AudioFileFormat 对象
      抛出：
      UnsupportedAudioFileException - 如果流没有指向系统识别的有效音频文件数据
      IOException - 如果发生输入/输出异常
      NullPointerException - 如果 stream 是 null
      参见：

    • getAudioFileFormat

      public static AudioFileFormat  getAudioFileFormat(URL  url) throws UnsupportedAudioFileException , IOException
      获取指定URL的音频文件格式。 URL 必须指向有效的音频文件数据。
      参数：
      url - 应从中提取文件格式信息的 URL
      返回：
      描述音频文件格式的 AudioFileFormat 对象
      抛出：
      UnsupportedAudioFileException - 如果 URL 未指向系统识别的有效音频文件数据
      IOException - 如果发生输入/输出异常
      NullPointerException - 如果 url 是 null

    • getAudioFileFormat

      public static AudioFileFormat  getAudioFileFormat(File  file) throws UnsupportedAudioFileException , IOException
      获取指定File的音频文件格式。 File 必须指向有效的音频文件数据。
      参数：
      file - 应从中提取文件格式信息的 File
      返回：
      描述音频文件格式的 AudioFileFormat 对象
      抛出：
      UnsupportedAudioFileException - 如果 File 未指向系统识别的有效音频文件数据
      IOException - 如果发生 I/O 异常
      NullPointerException - 如果 file 是 null

    • getAudioInputStream

      public static AudioInputStream  getAudioInputStream(InputStream  stream) throws UnsupportedAudioFileException , IOException
      从提供的输入流中获取音频输入流。流必须指向有效的音频文件数据。此方法的实现可能需要多个解析器来检查流以确定它们是否支持它。这些解析器必须能够标记流，读取足够的数据以确定它们是否支持流，并将流的读取指针重置到其原始位置。如果输入流不支持这些操作，此方法可能会失败并返回 IOException 。
      参数：
      stream - 应从中构造 AudioInputStream 的输入流
      返回：
      基于输入流中包含的音频文件数据的 AudioInputStream 对象
      抛出：
      UnsupportedAudioFileException - 如果流没有指向系统识别的有效音频文件数据
      IOException - 如果发生 I/O 异常
      NullPointerException - 如果 stream 是 null
      参见：

    • getAudioInputStream

      public static AudioInputStream  getAudioInputStream(URL  url) throws UnsupportedAudioFileException , IOException
      从提供的 URL 获取音频输入流。 URL 必须指向有效的音频文件数据。
      参数：
      url - 应为其构建 AudioInputStream 的 URL
      返回：
      基于 URL 指向的音频文件数据的 AudioInputStream 对象
      抛出：
      UnsupportedAudioFileException - 如果 URL 未指向系统识别的有效音频文件数据
      IOException - 如果发生 I/O 异常
      NullPointerException - 如果 url 是 null

    • getAudioInputStream

      public static AudioInputStream  getAudioInputStream(File  file) throws UnsupportedAudioFileException , IOException
      从提供的 File 获取音频输入流。 File 必须指向有效的音频文件数据。
      参数：
      file - 应为其构建 AudioInputStream 的 File
      返回：
      基于 File 指向的音频文件数据的 AudioInputStream 对象
      抛出：
      UnsupportedAudioFileException - 如果 File 未指向系统识别的有效音频文件数据
      IOException - 如果发生 I/O 异常
      NullPointerException - 如果 file 是 null

    • getAudioFileTypes

      public static AudioFileFormat.Type [] getAudioFileTypes()
      获取系统提供文件写入支持的文件类型。
      返回：
      一组独特的文件类型。如果不支持任何文件类型，则返回长度为 0 的数组。

    • isFileTypeSupported

      public static boolean isFileTypeSupported(AudioFileFormat.Type  fileType)
      系统是否提供对指定文件类型的文件写入支持。
      参数：
      fileType - 查询写入能力的文件类型
      返回：
      true 如果支持文件类型，否则 false
      抛出：
      NullPointerException - 如果 fileType 是 null

    • getAudioFileTypes

      public static AudioFileFormat.Type [] getAudioFileTypes(AudioInputStream  stream)
      从指定的音频输入流中获取系统可以写入的文件类型。
      参数：
      stream - 查询音频文件类型支持的音频输入流
      返回：
      文件类型数组。如果不支持任何文件类型，则返回长度为 0 的数组。
      抛出：
      NullPointerException - 如果 stream 是 null

    • isFileTypeSupported

      public static boolean isFileTypeSupported(AudioFileFormat.Type  fileType, AudioInputStream  stream)
      指示是否可以从指示的音频输入流写入指定文件类型的音频文件。
      参数：
      fileType - 查询写入能力的文件类型
      stream - 查询文件写入支持的流
      返回：
      true 如果此音频输入流支持文件类型，否则 false
      抛出：
      NullPointerException - 如果 fileType 或 stream 是 null

    • write

      public static int write(AudioInputStream  stream, AudioFileFormat.Type  fileType, OutputStream  out) throws IOException
      将表示指定文件类型的音频文件的字节流写入提供的输出流。有些文件类型要求将长度写入文件头；除非事先知道长度，否则不能从头到尾写入此类文件。如果音频文件类型的长度为 AudioSystem.NOT_SPECIFIED ，则尝试写入此类文件将失败并返回 IOException 。
      参数：
      stream - 包含要写入文件的音频数据的音频输入流
      fileType - 要写入的音频文件类型
      out - 文件数据应写入的流
      返回：
      写入输出流的字节数
      抛出：
      IOException - 如果发生输入/输出异常
      IllegalArgumentException - 如果系统不支持文件类型
      NullPointerException - 如果 stream 或 fileType 或 out 是 null
      参见：

    • write

      public static int write(AudioInputStream  stream, AudioFileFormat.Type  fileType, File  out) throws IOException
      将表示指定文件类型的音频文件的字节流写入提供的外部文件。
      参数：
      stream - 包含要写入文件的音频数据的音频输入流
      fileType - 要写入的音频文件类型
      out - 文件数据应写入的外部文件
      返回：
      写入文件的字节数
      抛出：
      IOException - 如果发生 I/O 异常
      IllegalArgumentException - 如果系统不支持文件类型
      NullPointerException - 如果 stream 或 fileType 或 out 是 null
      参见：