AudioSystem JDK 1.6)

Description

public class AudioSystem

The AudioSystem class acts as the entry point to the sampled-audio system resources.

The 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. In the Sun reference implementation, the properties file is "lib/sound.properties" in the JRE directory. 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 AudioSystem.getLine(javax.sound.sampled.Line.Info), AudioSystem.getClip()

javax.sound.sampled.Port Port AudioSystem.getLine(javax.sound.sampled.Line.Info)

javax.sound.sampled.SourceDataLine SourceDataLine AudioSystem.getLine(javax.sound.sampled.Line.Info), AudioSystem.getSourceDataLine(javax.sound.sampled.AudioFormat)

javax.sound.sampled.TargetDataLine TargetDataLine AudioSystem.getLine(javax.sound.sampled.Line.Info), AudioSystem.getTargetDataLine(javax.sound.sampled.AudioFormat)

The property value consists of the provider class name and the mixer name, separated by the hash mark ("#"). The provider class name is the fully-qualified name of a concrete 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.

Property Key	Interface	Affected Method(s)
`javax.sound.sampled.Clip`	`Clip`	`AudioSystem.getLine(javax.sound.sampled.Line.Info)`, `AudioSystem.getClip()`
`javax.sound.sampled.Port`	`Port`	`AudioSystem.getLine(javax.sound.sampled.Line.Info)`
`javax.sound.sampled.SourceDataLine`	`SourceDataLine`	`AudioSystem.getLine(javax.sound.sampled.Line.Info)`, `AudioSystem.getSourceDataLine(javax.sound.sampled.AudioFormat)`
`javax.sound.sampled.TargetDataLine`	`TargetDataLine`	`AudioSystem.getLine(javax.sound.sampled.Line.Info)`, `AudioSystem.getTargetDataLine(javax.sound.sampled.AudioFormat)`

If the provider class is specified, and it can be successully 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 AudioSystem.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 Mixerthat can be found in the list of all mixers is returned. If that fails, too, an IllegalArgumentException is thrown.

See also: AudioFormat AudioInputStream Mixer Line Line.Info

Methods

Hide/Show inherited methods

publicstatic AudioFileFormat getAudioFileFormat (File file) throws UnsupportedAudioFileException IOException

Obtains the audio file format of the specified File.

Obtains the audio file format of the specified File. The File must
point to valid audio file data.
Returns: an AudioFileFormat object describing the audio file format
Parameters:
- file - the File from which file format information should be extracted
Throws:
- UnsupportedAudioFileException - if the File does not point to valid audio file data recognized by the system
- IOException - if an I/O exception occurs

publicstatic AudioFileFormat getAudioFileFormat (InputStream stream) throws UnsupportedAudioFileException IOException

Obtains the audio file format of the provided input stream.

Obtains the audio file format of the provided input stream. The stream must
point to valid audio file data. The implementation of this method may require
multiple parsers to examine the stream to determine whether they support it.
These parsers must be able to mark the stream, read enough data to determine whether they
support the stream, and, if not, reset the stream's read pointer to its original
position. If the input stream does not support these operations, this method may fail
with an IOException.
Returns: an AudioFileFormat object describing the stream's audio file format
Parameters:
- stream - the input stream from which file format information should be extracted
Throws:
- UnsupportedAudioFileException - if the stream does not point to valid audio file data recognized by the system
- IOException - if an input/output exception occurs
See Also: InputStream.markSupported(), InputStream.mark(int),

publicstatic AudioFileFormat getAudioFileFormat (URL url) throws UnsupportedAudioFileException IOException

Obtains the audio file format of the specified URL.

Obtains the audio file format of the specified URL. The URL must
point to valid audio file data.
Returns: an AudioFileFormat object describing the audio file format
Parameters:
- url - the URL from which file format information should be extracted
Throws:
- UnsupportedAudioFileException - if the URL does not point to valid audio file data recognized by the system
- IOException - if an input/output exception occurs

publicstatic Type getAudioFileTypes ()

Obtains the file types for which file writing support is provided by the system.

publicstatic Type getAudioFileTypes (AudioInputStream stream)

Obtains the file types that the system can write from the audio input stream specified.

publicstatic AudioInputStream getAudioInputStream (Encoding targetEncoding, AudioInputStream sourceStream)

Obtains an audio input stream of the indicated encoding, by converting the provided audio input stream.

publicstatic AudioInputStream getAudioInputStream (AudioFormat targetFormat, AudioInputStream sourceStream)

Obtains an audio input stream of the indicated format, by converting the provided audio input stream.

publicstatic AudioInputStream getAudioInputStream (File file) throws UnsupportedAudioFileException IOException

Obtains an audio input stream from the provided File.

Obtains an audio input stream from the provided File. The File must
point to valid audio file data.
Returns: an AudioInputStream object based on the audio file data pointed to by the File
Parameters:
- file - the File for which the AudioInputStream should be constructed
Throws:
- UnsupportedAudioFileException - if the File does not point to valid audio file data recognized by the system
- IOException - if an I/O exception occurs

publicstatic AudioInputStream getAudioInputStream (InputStream stream) throws UnsupportedAudioFileException IOException

Obtains an audio input stream from the provided input stream.

Obtains an audio input stream from the provided input stream. The stream must
point to valid audio file data. The implementation of this method may
require multiple parsers to
examine the stream to determine whether they support it. These parsers must
be able to mark the stream, read enough data to determine whether they
support the stream, and, if not, reset the stream's read pointer to its original
position. If the input stream does not support these operation, this method may fail
with an IOException.
Returns: an AudioInputStream object based on the audio file data contained in the input stream.
Parameters:
- stream - the input stream from which the AudioInputStream should be constructed
Throws:
- UnsupportedAudioFileException - if the stream does not point to valid audio file data recognized by the system
- IOException - if an I/O exception occurs
See Also: InputStream.markSupported(), InputStream.mark(int),

publicstatic AudioInputStream getAudioInputStream (URL url) throws UnsupportedAudioFileException IOException

Obtains an audio input stream from the URL provided.

Obtains an audio input stream from the URL provided. The URL must
point to valid audio file data.
Returns: an AudioInputStream object based on the audio file data pointed to by the URL
Parameters:
- url - the URL for which the AudioInputStream should be constructed
Throws:
- UnsupportedAudioFileException - if the URL does not point to valid audio file data recognized by the system
- IOException - if an I/O exception occurs

publicstatic Clip getClip () throws LineUnavailableException

Obtains a clip that can be used for playing back an audio file or an audio stream.

Obtains a clip that can be used for playing back an audio file or an audio stream. The returned clip will be provided by the default system mixer, or, if not possible, by any other mixer installed in the system that supports a 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.
Returns: the desired clip object
Throws:
- LineUnavailableException - if a clip object is not available due to resource restrictions
- SecurityException - if a clip object is not available due to security restrictions
- IllegalArgumentException - if the system does not support at least one clip instance through any installed mixer
Since: 1.5
See Also: AudioSystem.getClip(Mixer.Info),

publicstatic Clip getClip (Info mixerInfo) throws LineUnavailableException

Obtains a clip from the specified mixer that can be used for playing back an audio file or an audio stream.

publicstatic Line getLine (Info info) throws LineUnavailableException

Obtains a line that matches the description in the specified 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.
Returns: a line of the requested kind
Parameters:
- info - a Line.Info object describing the desired kind of line
Throws:
- LineUnavailableException - if a matching line is not available due to resource restrictions
- SecurityException - if a matching line is not available due to security restrictions
- IllegalArgumentException - if the system does not support at least one line matching the specified Line.Info object through any installed mixer

publicstatic Mixer getMixer (Info info)

Obtains the requested audio mixer.

Obtains the requested audio mixer.
Returns: the requested mixer
Parameters:
- info - a Mixer.Info object representing the desired mixer, or null for the system default mixer
Throws:
- SecurityException - if the requested mixer is unavailable because of security restrictions
- IllegalArgumentException - if the info object does not represent a mixer installed on the system
See Also: AudioSystem.getMixerInfo(),

publicstatic Info getMixerInfo ()

Obtains an array of mixer info objects that represents the set of audio mixers that are currently installed on the system.

publicstatic SourceDataLine getSourceDataLine (AudioFormat format) throws LineUnavailableException

Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object.

Obtains a source data line that can be used for playing back audio data in the format specified by the 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.
Returns: the desired SourceDataLine object
Parameters:
- format - an AudioFormat object specifying the supported audio format of the returned line, or null for any audio format
Throws:
- LineUnavailableException - if a matching source data line is not available due to resource restrictions
- SecurityException - if a matching source data line is not available due to security restrictions
- IllegalArgumentException - if the system does not support at least one source data line supporting the specified audio format through any installed mixer
Since: 1.5
See Also: AudioSystem.getSourceDataLine(AudioFormat, Mixer.Info),

publicstatic SourceDataLine getSourceDataLine (AudioFormat format, Info mixerinfo) throws LineUnavailableException

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.

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.
Returns: the desired SourceDataLine object
Parameters:
- format - an AudioFormat object specifying the supported audio format of the returned line, or null for any audio format
- mixerinfo - a Mixer.Info object representing the desired mixer, or null for the system default mixer
Throws:
- LineUnavailableException - if a matching source data line is not available from the specified mixer due to resource restrictions
- SecurityException - if a matching source data line is not available from the specified mixer due to security restrictions
- IllegalArgumentException - if the specified mixer does not support at least one source data line supporting the specified audio format
Since: 1.5
See Also: AudioSystem.getSourceDataLine(AudioFormat),

publicstatic Info getSourceLineInfo (Info info)

Obtains information about all source lines of a particular type that are supported by the installed mixers.

Obtains information about all source lines of a particular type that are supported
by the installed mixers.
Returns: an array of Line.Info objects describing source lines matching the type requested. If no matching source lines are supported, an array of length 0 is returned.
Parameters:
- info - a Line.Info object that specifies the kind of lines about which information is requested
See Also: Mixer.getSourceLineInfo(Line.Info),

publicstatic TargetDataLine getTargetDataLine (AudioFormat format) throws LineUnavailableException

Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object.

Obtains a target data line that can be used for recording audio data in the format specified by the 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.
Returns: the desired TargetDataLine object
Parameters:
- format - an AudioFormat object specifying the supported audio format of the returned line, or null for any audio format
Throws:
- LineUnavailableException - if a matching target data line is not available due to resource restrictions
- SecurityException - if a matching target data line is not available due to security restrictions
- IllegalArgumentException - if the system does not support at least one target data line supporting the specified audio format through any installed mixer
Since: 1.5
See Also: AudioSystem.getTargetDataLine(AudioFormat, Mixer.Info), AudioPermission,

publicstatic TargetDataLine getTargetDataLine (AudioFormat format, Info mixerinfo) throws LineUnavailableException

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.

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.
Returns: the desired TargetDataLine object
Parameters:
- format - an AudioFormat object specifying the supported audio format of the returned line, or null for any audio format
- mixerinfo - a Mixer.Info object representing the desired mixer, or null for the system default mixer
Throws:
- LineUnavailableException - if a matching target data line is not available from the specified mixer due to resource restrictions
- SecurityException - if a matching target data line is not available from the specified mixer due to security restrictions
- IllegalArgumentException - if the specified mixer does not support at least one target data line supporting the specified audio format
Since: 1.5
See Also: AudioSystem.getTargetDataLine(AudioFormat), AudioPermission,

publicstatic Encoding getTargetEncodings (Encoding sourceEncoding)

Obtains the encodings that the system can obtain from an audio input stream with the specified encoding using the set of installed format converters.

Obtains the encodings that the system can obtain from an
audio input stream with the specified encoding using the set
of installed format converters.
Returns: array of encodings. If sourceEncodingis not supported, an array of length 0 is returned. Otherwise, the array will have a length of at least 1, representing sourceEncoding (no conversion).
Parameters:
- sourceEncoding - the encoding for which conversion support is queried

publicstatic Encoding getTargetEncodings (AudioFormat sourceFormat)

Obtains the encodings that the system can obtain from an audio input stream with the specified format using the set of installed format converters.

Obtains the encodings that the system can obtain from an
audio input stream with the specified format using the set
of installed format converters.
Returns: array of encodings. If sourceFormatis 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).
Parameters:
- sourceFormat - the audio format for which conversion is queried

publicstatic AudioFormat getTargetFormats (Encoding targetEncoding, AudioFormat sourceFormat)

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.

publicstatic Info getTargetLineInfo (Info info)

Obtains information about all target lines of a particular type that are supported by the installed mixers.

Obtains information about all target lines of a particular type that are supported
by the installed mixers.
Returns: an array of Line.Info objects describing target lines matching the type requested. If no matching target lines are supported, an array of length 0 is returned.
Parameters:
- info - a Line.Info object that specifies the kind of lines about which information is requested
See Also: Mixer.getTargetLineInfo(Line.Info),

publicstatic boolean isConversionSupported (Encoding targetEncoding, AudioFormat sourceFormat)

Indicates whether an audio input stream of the specified encoding can be obtained from an audio input stream that has the specified format.

Indicates whether an audio input stream of the specified encoding
can be obtained from an audio input stream that has the specified
format.
Returns: true if the conversion is supported, otherwise false
Parameters:
- targetEncoding - the desired encoding after conversion
- sourceFormat - the audio format before conversion

publicstatic boolean isConversionSupported (AudioFormat targetFormat, AudioFormat sourceFormat)

Indicates whether an audio input stream of a specified format can be obtained from an audio input stream of another specified format.

Indicates whether an audio input stream of a specified format
can be obtained from an audio input stream of another specified format.
Returns: true if the conversion is supported, otherwise false
Parameters:
- targetFormat - the desired audio format after conversion
- sourceFormat - the audio format before conversion

publicstatic boolean isFileTypeSupported (Type fileType)

Indicates whether file writing support for the specified file type is provided by the system.

Indicates whether file writing support for the specified file type is provided
by the system.
Returns: true if the file type is supported, otherwise false
Parameters:
- fileType - the file type for which write capabilities are queried

publicstatic boolean isFileTypeSupported (Type fileType, AudioInputStream stream)

Indicates whether an audio file of the specified file type can be written from the indicated audio input stream.

Indicates whether an audio file of the specified file type can be written
from the indicated audio input stream.
Returns: true if the file type is supported for this audio input stream, otherwise false
Parameters:
- fileType - the file type for which write capabilities are queried
- stream - the stream for which file-writing support is queried

publicstatic boolean isLineSupported (Info info)

Indicates whether the system supports any lines that match the specified Line.Info object.

Indicates whether the system supports any lines that match
the specified Line.Info object. A line is supported if
any installed mixer supports it.
Returns: true if at least one matching line is supported, otherwise false
Parameters:
- info - a Line.Info object describing the line for which support is queried
See Also: Mixer.isLineSupported(Line.Info),

publicstatic int write (AudioInputStream stream, Type fileType, File out) throws IOException

Writes a stream of bytes representing an audio file of the specified file type to the external file provided.

publicstatic int write (AudioInputStream stream, Type fileType, OutputStream out) throws IOException

Writes a stream of bytes representing an audio file of the specified file type to the output stream provided.

Writes a stream of bytes representing an audio file of the specified file type
to the output stream provided. Some file types require that
the length be written into the file header; such files cannot be written from
start to finish unless the length is known in advance. An attempt
to write a file of such a type will fail with an IOException if the length in
the audio file type is AudioSystem.NOT_SPECIFIED.
Returns: the number of bytes written to the output stream
Parameters:
- stream - the audio input stream containing audio data to be written to the file
- fileType - the kind of audio file to write
- out - the stream to which the file data should be written
Throws:
- IOException - if an input/output exception occurs
- IllegalArgumentException - if the file type is not supported by the system
See Also: AudioSystem.isFileTypeSupported(javax.sound.sampled.AudioFileFormat.Type), AudioSystem.getAudioFileTypes(),