javax.sound.sampled
Class AudioSystem

java.lang.Object
  |
  +--javax.sound.sampled.AudioSystem

public class AudioSystem

extends Object

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.

Since:

1.3

See Also:

AudioFormat, AudioInputStream, Mixer, Line, Line.Info

Field Summary

static int

NOT_SPECIFIED An integer that stands for an unknown numeric value.

Method Summary

static AudioFileFormat	getAudioFileFormat(File file) Obtains the audio file format of the specified File.
static AudioFileFormat	getAudioFileFormat(InputStream stream) Obtains the audio file format of the provided input stream.
static AudioFileFormat	getAudioFileFormat(URL url) 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(AudioInputStream stream) Obtains the file types that the system can write from the audio input stream specified.
static AudioInputStream	getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream of the indicated encoding, by converting the provided audio input stream.
static AudioInputStream	getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream of the indicated format, by converting the provided audio input stream.
static AudioInputStream	getAudioInputStream(File file) Obtains an audio input stream from the provided File.
static AudioInputStream	getAudioInputStream(InputStream stream) Obtains an audio input stream from the provided input stream.
static AudioInputStream	getAudioInputStream(URL url) Obtains an audio input stream from the URL provided.
static Line	getLine(Line.Info info) Obtains a line that matches the description in the specified Line.Info object.
static Mixer	getMixer(Mixer.Info info) 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 Line.Info[]	getSourceLineInfo(Line.Info info) Obtains information about source lines of a particular type that are supported by any installed mixer.
static AudioFormat.Encoding[]	getTargetEncodings(AudioFormat.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.
static AudioFormat.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.
static AudioFormat[]	getTargetFormats(AudioFormat.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.
static Line.Info[]	getTargetLineInfo(Line.Info info) Obtains information about target lines of a particular type that are supported by any installed mixer.
static boolean	isConversionSupported(AudioFormat.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.
static 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.
static boolean	isFileTypeSupported(AudioFileFormat.Type fileType) Indicates whether file writing support for the specified file type is provided by the system.
static boolean	isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream) Indicates whether an audio file of the specified file type can be written from the indicated audio input stream.
static boolean	isLineSupported(Line.Info info) Indicates whether the the system supports any lines that match the specified Line.Info object.
static int	write(AudioInputStream stream, AudioFileFormat.Type fileType, File out) Writes a stream of bytes representing an audio file of the specified file type to the external file provided.
static int	write(AudioInputStream stream, AudioFileFormat.Type fileType, OutputStream out) Writes a stream of bytes representing an audio file of the specified file type to the output stream provided.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NOT_SPECIFIED

public static final int NOT_SPECIFIED

An integer that stands for an unknown numeric value. This value is appropriate only for signed quantities that do not normally take negative values. Examples include file sizes, frame sizes, buffer sizes, and sample rates. A number of Java Sound constructors accept a value of NOT_SPECIFIED for such parameters. Other methods may also accept or return this value, as documented.

Method Detail

getMixerInfo

public 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.

Returns:

an array of info objects for the currently installed mixers. If no mixers are available on the system, an array of length 0 is returned.

See Also:

getMixer(javax.sound.sampled.Mixer.Info)

getMixer

public static Mixer getMixer(Mixer.Info info)

Obtains the requested audio mixer.

Parameters:

info - a Mixer.Info object representing the desired mixer, or null for the system default mixer

Returns:

the requested 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:

getMixerInfo()

getSourceLineInfo

public static Line.Info[] getSourceLineInfo(Line.Info info)

Obtains information about source lines of a particular type that are supported by any installed mixer.

Parameters:

info - a Line.Info object that specifies the kind of lines about which information is requested

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.

See Also:

Mixer.getSourceLineInfo(Line.Info)

getTargetLineInfo

public static Line.Info[] getTargetLineInfo(Line.Info info)

Obtains information about target lines of a particular type that are supported by any installed mixer.

Parameters:

info - a Line.Info object that specifies the kind of lines about which information is requested

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.

See Also:

Mixer.getTargetLineInfo(Line.Info)

isLineSupported

public static boolean isLineSupported(Line.Info info)

Indicates whether the the system supports any lines that match the specified Line.Info object. A line is supported if any installed mixer supports it.

Parameters:

info - a Line.Info object describing the line for which support is queried

Returns:

true if at least one matching line is supported, otherwise false

See Also:

Mixer.isLineSupported(Line.Info)

getLine

public static Line getLine(Line.Info info)
                    throws LineUnavailableException

Obtains a line that matches the description in the specified Line.Info object.

Parameters:

info - a Line.Info object describing the desired kind of line

Returns:

a line of the requested kind

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

getTargetEncodings

public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.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.

Parameters:

sourceEncoding - the encoding for which conversion support is queried

Returns:

array of encodings. The array will always have a length of at least 1, representing the current encoding (no conversion).

getTargetEncodings

public static AudioFormat.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.

Parameters:

sourceFormat - the audio format for which conversion is queried

Returns:

array of encodings. The array will always have a length of at least 1, representing the current encoding (no conversion).

isConversionSupported

public static boolean isConversionSupported(AudioFormat.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.

Parameters:

targetEncoding - the desired encoding after conversion

sourceFormat - the audio format before conversion

Returns:

true if the conversion is supported, otherwise false

getAudioInputStream

public static AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding,
                                                   AudioInputStream sourceStream)

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

Parameters:

targetEncoding - the desired encoding after conversion

sourceStream - the stream to be converted

Returns:

an audio input stream of the indicated encoding

Throws:

IllegalArgumentException - if the conversion is not supported

See Also:

getTargetEncodings(AudioFormat.Encoding), getTargetEncodings(AudioFormat), isConversionSupported(AudioFormat.Encoding, AudioFormat), getAudioInputStream(AudioFormat, AudioInputStream)

getTargetFormats

public static AudioFormat[] getTargetFormats(AudioFormat.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.

Parameters:

targetEncoding - the desired encoding after conversion

sourceFormat - the audio format before conversion

Returns:

array of formats. If no formats of the specified encoding are supported, an array of length 0 is returned.

isConversionSupported

public static 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.

Parameters:

targetFormat - the desired audio format after conversion

sourceFormat - the audio format before conversion

Returns:

true if the conversion is supported, otherwise false

getAudioInputStream

public static AudioInputStream getAudioInputStream(AudioFormat targetFormat,
                                                   AudioInputStream sourceStream)

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

Parameters:

targetFormat - the desired audio format after conversion

sourceStream - the stream to be converted

Returns:

an audio input stream of the indicated format

Throws:

IllegalArgumentException - if the conversion is not supported #see #getTargetEncodings(AudioFormat)

See Also:

getTargetFormats(AudioFormat.Encoding, AudioFormat), isConversionSupported(AudioFormat, AudioFormat), getAudioInputStream(AudioFormat.Encoding, AudioInputStream)

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(InputStream stream)
                                          throws UnsupportedAudioFileException,
                                                 IOException

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.

Parameters:

stream - the input stream from which file format information should be extracted

Returns:

an AudioFileFormat object describing the stream's audio file format

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)

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(URL url)
                                          throws UnsupportedAudioFileException,
                                                 IOException

Obtains the audio file format of the specified URL. The URL must point to valid audio file data.

Parameters:

url - the URL from which file format information should be extracted

Returns:

an AudioFileFormat object describing the audio file format

Throws:

UnsupportedAudioFileException - if the URL does not point to valid audio file data recognized by the system

IOException - if an input/output exception occurs

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(File file)
                                          throws UnsupportedAudioFileException,
                                                 IOException

Obtains the audio file format of the specified File. The File must point to valid audio file data.

Parameters:

file - the File from which file format information should be extracted

Returns:

an AudioFileFormat object describing the audio file format

Throws:

UnsupportedAudioFileException - if the File does not point to valid audio file data recognized by the system

IOException - if an I/O exception occurs

getAudioInputStream

public static AudioInputStream getAudioInputStream(InputStream stream)
                                            throws UnsupportedAudioFileException,
                                                   IOException

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.

Parameters:

stream - the input stream from which the AudioInputStream should be constructed

Returns:

an AudioInputStream object based on the audio file data contained in the input stream.

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)

getAudioInputStream

public static AudioInputStream getAudioInputStream(URL url)
                                            throws UnsupportedAudioFileException,
                                                   IOException

Obtains an audio input stream from the URL provided. The URL must point to valid audio file data.

Parameters:

url - the URL for which the AudioInputStream should be constructed

Returns:

an AudioInputStream object based on the audio file data pointed to by the URL

Throws:

UnsupportedAudioFileException - if the URL does not point to valid audio file data recognized by the system

IOException - if an I/O exception occurs

getAudioInputStream

public static AudioInputStream getAudioInputStream(File file)
                                            throws UnsupportedAudioFileException,
                                                   IOException

Obtains an audio input stream from the provided File. The File must point to valid audio file data.

Parameters:

file - the File for which the AudioInputStream should be constructed

Returns:

an AudioInputStream object based on the audio file data pointed to by the File

Throws:

UnsupportedAudioFileException - if the File does not point to valid audio file data recognized by the system

IOException - if an I/O exception occurs

getAudioFileTypes

public static AudioFileFormat.Type[] getAudioFileTypes()

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

Returns:

array of file types. If no file types are supported, an array of length 0 is returned.

isFileTypeSupported

public static boolean isFileTypeSupported(AudioFileFormat.Type fileType)

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

Parameters:

fileType - the file type for which write capabilities are queried

Returns:

true if the file type is supported, otherwise false

getAudioFileTypes

public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream)

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

Parameters:

stream - the audio input stream for which audio file type support is queried

Returns:

array of file types. If no file types are supported, an array of length 0 is returned.

isFileTypeSupported

public static boolean isFileTypeSupported(AudioFileFormat.Type fileType,
                                          AudioInputStream stream)

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

Parameters:

fileType - the file type for which write capabilities are queried

stream - the stream for which file-writing support is queried

Returns:

true if the file type is supported for this audio input stream, otherwise false

write

public static int write(AudioInputStream stream,
                        AudioFileFormat.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. 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.

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

Returns:

the number of bytes written to the output stream

Throws:

IOException - if an input/output exception occurs

IllegalArgumentException - if the file type is not supported by the system

See Also:

isFileTypeSupported(javax.sound.sampled.AudioFileFormat.Type), getAudioFileTypes()

write

public static int write(AudioInputStream stream,
                        AudioFileFormat.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.

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 external file to which the file data should be written

Returns:

the number of bytes written to the file

Throws:

IOException - if an I/O exception occurs

IllegalArgumentException - if the file type is not supported by the system

See Also:

isFileTypeSupported(javax.sound.sampled.AudioFileFormat.Type), getAudioFileTypes()