public class AudioSystem extends Object
AudioSystem
class acts as the entry point to the sampled-audio system resources. This class lets you query and access the mixers that are installed on the system. AudioSystem
includes a number of methods for converting audio data between different formats, and for translating between audio files and streams. It also provides a method for obtaining a Line
directly from the AudioSystem
without dealing explicitly with mixers. Properties can be used to specify the default mixer for specific line types. Both system properties and a properties file are considered. The "sound.properties" properties file is read from an implementation-specific location (typically it is the conf
directory in the Java installation directory). The optional "javax.sound.config.file" system property can be used to specify the properties file that will be read as the initial configuration. If a property exists both as a system property and in the properties file, the system property takes precedence. If none is specified, a suitable default is chosen among the available devices. The syntax of the properties file is specified in Properties.load
. The following table lists the available property keys and which methods consider them:
Property Key | Interface | Affected Method(s) |
---|---|---|
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
class. The mixer name is matched against the String
returned by the getName
method of Mixer.Info
. Either the class name, or the mixer name may be omitted. If only the class name is specified, the trailing hash mark is optional. If the provider class is specified, and it can be successfully retrieved from the installed providers, the list of Mixer.Info
objects is retrieved from the provider. Otherwise, or when these mixers do not provide a subsequent match, the list is retrieved from getMixerInfo()
to contain all available Mixer.Info
objects.
If a mixer name is specified, the resulting list of Mixer.Info
objects is searched: the first one with a matching name, and whose Mixer
provides the respective line interface, will be returned. If no matching Mixer.Info
object is found, or the mixer name is not specified, the first mixer from the resulting list, which provides the respective line interface, will be returned.
For example, the property javax.sound.sampled.Clip
with a value "com.sun.media.sound.MixerProvider#SunClip"
will have the following consequences when getLine
is called requesting a Clip
instance: if the class com.sun.media.sound.MixerProvider
exists in the list of installed mixer providers, the first Clip
from the first mixer with name "SunClip"
will be returned. If it cannot be found, the first Clip
from the first mixer of the specified provider will be returned, regardless of name. If there is none, the first Clip
from the first Mixer
with name "SunClip"
in the list of all mixers (as returned by getMixerInfo
) will be returned, or, if not found, the first Clip
of the first Mixer
that can be found in the list of all mixers is returned. If that fails, too, an IllegalArgumentException
is thrown.
Modifier and Type | Field | Description |
---|---|---|
static final int |
NOT_SPECIFIED |
An integer that stands for an unknown numeric value. |
Modifier and Type | Method | Description |
---|---|---|
static AudioFileFormat |
getAudioFileFormat |
Obtains the audio file format of the specified File . |
static AudioFileFormat |
getAudioFileFormat |
Obtains the audio file format of the provided input stream. |
static AudioFileFormat |
getAudioFileFormat |
Obtains the audio file format of the specified URL . |
static AudioFileFormat.Type[] |
getAudioFileTypes() |
Obtains the file types for which file writing support is provided by the system. |
static AudioFileFormat.Type[] |
getAudioFileTypes |
Obtains the file types that the system can write from the audio input stream specified. |
static AudioInputStream |
getAudioInputStream |
Obtains an audio input stream from the provided File . |
static AudioInputStream |
getAudioInputStream |
Obtains an audio input stream from the provided input stream. |
static AudioInputStream |
getAudioInputStream |
Obtains an audio input stream from the URL provided. |
static AudioInputStream |
getAudioInputStream |
Obtains an audio input stream of the indicated encoding, by converting the provided audio input stream. |
static AudioInputStream |
getAudioInputStream |
Obtains an audio input stream of the indicated format, by converting the provided audio input stream. |
static Clip |
getClip() |
Obtains a clip that can be used for playing back an audio file or an audio stream. |
static Clip |
getClip |
Obtains a clip from the specified mixer that can be used for playing back an audio file or an audio stream. |
static Line |
getLine |
Obtains a line that matches the description in the specified Line.Info object. |
static Mixer |
getMixer |
Obtains the requested audio mixer. |
static Mixer.Info[] |
getMixerInfo() |
Obtains an array of mixer info objects that represents the set of audio mixers that are currently installed on the system. |
static SourceDataLine |
getSourceDataLine |
Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object. |
static SourceDataLine |
getSourceDataLine |
Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object. |
static Line.Info[] |
getSourceLineInfo |
Obtains information about all source lines of a particular type that are supported by the installed mixers. |
static TargetDataLine |
getTargetDataLine |
Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object. |
static TargetDataLine |
getTargetDataLine |
Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object. |
static AudioFormat.Encoding[] |
getTargetEncodings |
Obtains the encodings that the system can obtain from an audio input stream with the specified format using the set of installed format converters. |
static AudioFormat.Encoding[] |
getTargetEncodings |
Obtains the encodings that the system can obtain from an audio input stream with the specified encoding using the set of installed format converters. |
static AudioFormat[] |
getTargetFormats |
Obtains the formats that have a particular encoding and that the system can obtain from a stream of the specified format using the set of installed format converters. |
static Line.Info[] |
getTargetLineInfo |
Obtains information about all target lines of a particular type that are supported by the installed mixers. |
static boolean |
isConversionSupported |
Indicates whether an audio input stream of the specified encoding can be obtained from an audio input stream that has the specified format. |
static boolean |
isConversionSupported |
Indicates whether an audio input stream of a specified format can be obtained from an audio input stream of another specified format. |
static boolean |
isFileTypeSupported |
Indicates whether file writing support for the specified file type is provided by the system. |
static boolean |
isFileTypeSupported |
Indicates whether an audio file of the specified file type can be written from the indicated audio input stream. |
static boolean |
isLineSupported |
Indicates whether the system supports any lines that match the specified Line.Info object. |
static int |
write |
Writes a stream of bytes representing an audio file of the specified file type to the external file provided. |
static int |
write |
Writes a stream of bytes representing an audio file of the specified file type to the output stream provided. |
public static final int NOT_SPECIFIED
NOT_SPECIFIED
for such parameters. Other methods may also accept or return this value, as documented.public static Mixer.Info[] getMixerInfo()
public static Mixer getMixer(Mixer.Info info)
info
- a Mixer.Info
object representing the desired mixer, or null
for the system default mixerSecurityException
- if the requested mixer is unavailable because of security restrictionsIllegalArgumentException
- if the info object does not represent a mixer installed on the systempublic static Line.Info[] getSourceLineInfo(Line.Info info)
info
- a Line.Info
object that specifies the kind of lines about which information is requestedLine.Info
objects describing source lines matching the type requested. If no matching source lines are supported, an array of length 0 is returned.public static Line.Info[] getTargetLineInfo(Line.Info info)
info
- a Line.Info
object that specifies the kind of lines about which information is requestedLine.Info
objects describing target lines matching the type requested. If no matching target lines are supported, an array of length 0 is returned.public static boolean isLineSupported(Line.Info info)
Line.Info
object. A line is supported if any installed mixer supports it.info
- a Line.Info
object describing the line for which support is queriedtrue
if at least one matching line is supported, otherwise false
public static Line getLine(Line.Info info) throws LineUnavailableException
Line.Info
object. If a DataLine
is requested, and info
is an instance of DataLine.Info
specifying at least one fully qualified audio format, the last one will be used as the default format of the returned DataLine
.
If system properties javax.sound.sampled.Clip
, javax.sound.sampled.Port
, javax.sound.sampled.SourceDataLine
and javax.sound.sampled.TargetDataLine
are defined or they are defined in the file "sound.properties", they are used to retrieve default lines. For details, refer to the class description
. If the respective property is not set, or the mixer requested in the property is not installed or does not provide the requested line, all installed mixers are queried for the requested line type. A Line will be returned from the first mixer providing the requested line type.
info
- a Line.Info
object describing the desired kind of lineLineUnavailableException
- if a matching line is not available due to resource restrictionsSecurityException
- if a matching line is not available due to security restrictionsIllegalArgumentException
- if the system does not support at least one line matching the specified Line.Info
object through any installed mixerpublic static Clip getClip() throws LineUnavailableException
Clip
object. The returned clip must be opened with the open(AudioFormat)
or open(AudioInputStream)
method.
This is a high-level method that uses getMixer
and getLine
internally.
If the system property javax.sound.sampled.Clip
is defined or it is defined in the file "sound.properties", it is used to retrieve the default clip. For details, refer to the class description
.
LineUnavailableException
- if a clip object is not available due to resource restrictionsSecurityException
- if a clip object is not available due to security restrictionsIllegalArgumentException
- if the system does not support at least one clip instance through any installed mixerpublic static Clip getClip(Mixer.Info mixerInfo) throws LineUnavailableException
The returned clip must be opened with the open(AudioFormat)
or open(AudioInputStream)
method.
This is a high-level method that uses getMixer
and getLine
internally.
mixerInfo
- a Mixer.Info
object representing the desired mixer, or null
for the system default mixerLineUnavailableException
- if a clip is not available from this mixer due to resource restrictionsSecurityException
- if a clip is not available from this mixer due to security restrictionsIllegalArgumentException
- if the system does not support at least one clip through the specified mixerpublic static SourceDataLine getSourceDataLine(AudioFormat format) throws LineUnavailableException
AudioFormat
object. The returned line will be provided by the default system mixer, or, if not possible, by any other mixer installed in the system that supports a matching SourceDataLine
object. The returned line should be opened with the open(AudioFormat)
or open(AudioFormat, int)
method.
This is a high-level method that uses getMixer
and getLine
internally.
The returned SourceDataLine
's default audio format will be initialized with format
.
If the system property javax.sound.sampled.SourceDataLine
is defined or it is defined in the file "sound.properties", it is used to retrieve the default source data line. For details, refer to the class description
.
format
- an AudioFormat
object specifying the supported audio format of the returned line, or null
for any audio formatSourceDataLine
objectLineUnavailableException
- if a matching source data line is not available due to resource restrictionsSecurityException
- if a matching source data line is not available due to security restrictionsIllegalArgumentException
- if the system does not support at least one source data line supporting the specified audio format through any installed mixerpublic static SourceDataLine getSourceDataLine(AudioFormat format, Mixer.Info mixerinfo) throws LineUnavailableException
AudioFormat
object, provided by the mixer specified by the Mixer.Info
object. The returned line should be opened with the open(AudioFormat)
or open(AudioFormat, int)
method.
This is a high-level method that uses getMixer
and getLine
internally.
The returned SourceDataLine
's default audio format will be initialized with format
.
format
- an AudioFormat
object specifying the supported audio format of the returned line, or null
for any audio formatmixerinfo
- a Mixer.Info
object representing the desired mixer, or null
for the system default mixerSourceDataLine
objectLineUnavailableException
- if a matching source data line is not available from the specified mixer due to resource restrictionsSecurityException
- if a matching source data line is not available from the specified mixer due to security restrictionsIllegalArgumentException
- if the specified mixer does not support at least one source data line supporting the specified audio formatpublic static TargetDataLine getTargetDataLine(AudioFormat format) throws LineUnavailableException
AudioFormat
object. The returned line will be provided by the default system mixer, or, if not possible, by any other mixer installed in the system that supports a matching TargetDataLine
object. The returned line should be opened with the open(AudioFormat)
or open(AudioFormat, int)
method.
This is a high-level method that uses getMixer
and getLine
internally.
The returned TargetDataLine
's default audio format will be initialized with format
.
If the system property javax.sound.sampled.TargetDataLine
is defined or it is defined in the file "sound.properties", it is used to retrieve the default target data line. For details, refer to the class description
.
format
- an AudioFormat
object specifying the supported audio format of the returned line, or null
for any audio formatTargetDataLine
objectLineUnavailableException
- if a matching target data line is not available due to resource restrictionsSecurityException
- if a matching target data line is not available due to security restrictionsIllegalArgumentException
- if the system does not support at least one target data line supporting the specified audio format through any installed mixerpublic static TargetDataLine getTargetDataLine(AudioFormat format, Mixer.Info mixerinfo) throws LineUnavailableException
AudioFormat
object, provided by the mixer specified by the Mixer.Info
object. The returned line should be opened with the open(AudioFormat)
or open(AudioFormat, int)
method.
This is a high-level method that uses getMixer
and getLine
internally.
The returned TargetDataLine
's default audio format will be initialized with format
.
format
- an AudioFormat
object specifying the supported audio format of the returned line, or null
for any audio formatmixerinfo
- a Mixer.Info
object representing the desired mixer, or null
for the system default mixerTargetDataLine
objectLineUnavailableException
- if a matching target data line is not available from the specified mixer due to resource restrictionsSecurityException
- if a matching target data line is not available from the specified mixer due to security restrictionsIllegalArgumentException
- if the specified mixer does not support at least one target data line supporting the specified audio formatpublic static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding)
sourceEncoding
- the encoding for which conversion support is queriedsourceEncoding
is not supported, an array of length 0 is returned. Otherwise, the array will have a length of at least 1, representing sourceEncoding
(no conversion).NullPointerException
- if sourceEncoding
is null
public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat)
sourceFormat
- the audio format for which conversion is queriedsourceFormat
is not supported, an array of length 0 is returned. Otherwise, the array will have a length of at least 1, representing the encoding of sourceFormat
(no conversion).NullPointerException
- if sourceFormat
is null
public static boolean isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat)
targetEncoding
- the desired encoding after conversionsourceFormat
- the audio format before conversiontrue
if the conversion is supported, otherwise false
NullPointerException
- if targetEncoding
or sourceFormat
are null
public static AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream)
targetEncoding
- the desired encoding after conversionsourceStream
- the stream to be convertedIllegalArgumentException
- if the conversion is not supportedNullPointerException
- if targetEncoding
or sourceStream
are null
public static AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat)
targetEncoding
- the desired encoding after conversionsourceFormat
- the audio format before conversionNullPointerException
- if targetEncoding
or sourceFormat
are null
public static boolean isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat)
targetFormat
- the desired audio format after conversionsourceFormat
- the audio format before conversiontrue
if the conversion is supported, otherwise false
NullPointerException
- if targetFormat
or sourceFormat
are null
public static AudioInputStream getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream)
targetFormat
- the desired audio format after conversionsourceStream
- the stream to be convertedIllegalArgumentException
- if the conversion is not supportedNullPointerException
- if targetFormat
or sourceStream
are null
public static AudioFileFormat getAudioFileFormat(InputStream stream) throws UnsupportedAudioFileException, IOException
IOException
.stream
- the input stream from which file format information should be extractedAudioFileFormat
object describing the stream's audio file formatUnsupportedAudioFileException
- if the stream does not point to valid audio file data recognized by the systemIOException
- if an input/output exception occursNullPointerException
- if stream
is null
public static AudioFileFormat getAudioFileFormat(URL url) throws UnsupportedAudioFileException, IOException
URL
. The URL
must point to valid audio file data.url
- the URL
from which file format information should be extractedAudioFileFormat
object describing the audio file formatUnsupportedAudioFileException
- if the URL
does not point to valid audio file data recognized by the systemIOException
- if an input/output exception occursNullPointerException
- if url
is null
public static AudioFileFormat getAudioFileFormat(File file) throws UnsupportedAudioFileException, IOException
File
. The File
must point to valid audio file data.file
- the File
from which file format information should be extractedAudioFileFormat
object describing the audio file formatUnsupportedAudioFileException
- if the File
does not point to valid audio file data recognized by the systemIOException
- if an I/O exception occursNullPointerException
- if file
is null
public static AudioInputStream getAudioInputStream(InputStream stream) throws UnsupportedAudioFileException, IOException
IOException
.stream
- the input stream from which the AudioInputStream
should be constructedAudioInputStream
object based on the audio file data contained in the input streamUnsupportedAudioFileException
- if the stream does not point to valid audio file data recognized by the systemIOException
- if an I/O exception occursNullPointerException
- if stream
is null
public static AudioInputStream getAudioInputStream(URL url) throws UnsupportedAudioFileException, IOException
URL
provided. The URL
must point to valid audio file data.url
- the URL
for which the AudioInputStream
should be constructedAudioInputStream
object based on the audio file data pointed to by the URL
UnsupportedAudioFileException
- if the URL
does not point to valid audio file data recognized by the systemIOException
- if an I/O exception occursNullPointerException
- if url
is null
public static AudioInputStream getAudioInputStream(File file) throws UnsupportedAudioFileException, IOException
File
. The File
must point to valid audio file data.file
- the File
for which the AudioInputStream
should be constructedAudioInputStream
object based on the audio file data pointed to by the File
UnsupportedAudioFileException
- if the File
does not point to valid audio file data recognized by the systemIOException
- if an I/O exception occursNullPointerException
- if file
is null
public static AudioFileFormat.Type[] getAudioFileTypes()
public static boolean isFileTypeSupported(AudioFileFormat.Type fileType)
fileType
- the file type for which write capabilities are queriedtrue
if the file type is supported, otherwise false
NullPointerException
- if fileType
is null
public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream)
stream
- the audio input stream for which audio file type support is queriedNullPointerException
- if stream
is null
public static boolean isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream)
fileType
- the file type for which write capabilities are queriedstream
- the stream for which file-writing support is queriedtrue
if the file type is supported for this audio input stream, otherwise false
NullPointerException
- if fileType
or stream
are null
public static int write(AudioInputStream stream, AudioFileFormat.Type fileType, OutputStream out) throws IOException
IOException
if the length in the audio file type is AudioSystem.NOT_SPECIFIED
.stream
- the audio input stream containing audio data to be written to the filefileType
- the kind of audio file to writeout
- the stream to which the file data should be writtenIOException
- if an input/output exception occursIllegalArgumentException
- if the file type is not supported by the systemNullPointerException
- if stream
or fileType
or out
are null
public static int write(AudioInputStream stream, AudioFileFormat.Type fileType, File out) throws IOException
stream
- the audio input stream containing audio data to be written to the filefileType
- the kind of audio file to writeout
- the external file to which the file data should be writtenIOException
- if an I/O exception occursIllegalArgumentException
- if the file type is not supported by the systemNullPointerException
- if stream
or fileType
or out
are null
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/sound/sampled/AudioSystem.html