Module java.desktop
Package javax.sound.sampled

Class AudioSystem

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

属性可用于指定特定线路类型的默认混音器。系统属性和属性文件都会被考虑。将从特定于实现的位置（通常是Java安装目录中的conf目录）读取名为“sound.properties”的属性文件。可选的“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.Info的getName方法返回的String进行匹配。可以省略类名或混音器名称。如果只指定类名，则尾随的井号是可选的。

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

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

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

自从:
1.3
参见:

  • Field Details

    • NOT_SPECIFIED

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

  • Method Details

    • getMixerInfo

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

    • getMixer

      public static Mixer getMixer(Mixer.Info info)
      获取请求的音频混音器。
      参数:
      info - 一个表示所需混音器的Mixer.Info对象，或者为系统默认混音器的null
      返回:
      请求的混音器
      抛出:
      SecurityException - 如果由于安全限制而无法使用请求的混音器
      IllegalArgumentException - 如果info对象不代表系统上安装的混音器
      参见:

    • 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"中被定义，它们将用于检索默认线路。有关详细信息，请参阅类描述。如果未设置相应属性，或者属性中请求的混音器未安装或未提供请求的线路，则将查询所有已安装的混音器以获取请求的线路类型。将从提供请求线路类型的第一个混音器返回一条线路。

      参数:
      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"中被定义，它将用于检索默认剪辑。有关详细信息，请参阅类描述。

      返回:
      所需的剪辑对象
      抛出:
      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"中被定义，它将用于检索默认源数据线。有关详细信息，请参阅类描述。

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

    • getSourceDataLine

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

      返回的线路应使用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"中定义了它，则将用于检索默认目标数据线路。有关详细信息，请参阅类描述。

      参数:
      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
      参见: