javax.sound.sampled

Class AudioSystem


public class AudioSystem
extends Object

This clas is the primary interface to the audio system. It contains a number of static methods which can be used to access this package's functionality.
Since:
1.3

Field Summary

static int
NOT_SPECIFIED
A constant which can be passed to a number of methods in this package, to indicate an unspecified value.

Method Summary

static AudioFileFormat
getAudioFileFormat(File f)
Return the file format of a given File.
static AudioFileFormat
getAudioFileFormat(InputStream is)
Return the file format of a given input stream.
static AudioFileFormat
getAudioFileFormat(URL url)
Return the file format of a given URL.
static AudioFileFormat.Type[]
getAudioFileTypes()
Return an array of all the supported AudioFileFormat types.
static AudioFileFormat.Type[]
getAudioFileTypes(AudioInputStream ais)
Return an array of all the supported AudioFileFormat types which match the given audio input stream
static AudioInputStream
getAudioInputStream(File f)
Return an audio input stream for the file.
static AudioInputStream
getAudioInputStream(InputStream is)
Return an audio input stream given an input stream.
static AudioInputStream
getAudioInputStream(URL url)
Return an audio input stream for the given URL.
static AudioInputStream
getAudioInputStream(AudioFormat targ, AudioInputStream ais)
Given an audio input stream, this will try to create a new audio input stream whose format matches the given target format.
static AudioInputStream
getAudioInputStream(AudioFormat.Encoding targ, AudioInputStream ais)
Given an audio input stream, this will try to create a new audio input stream whose encoding matches the given target encoding.
static Clip
getClip()
Return a new clip which can be used for playing back an audio stream.
static Clip
getClip(Mixer.Info info)
Return a new clip which can be used for playing back an audio stream.
static Line
getLine(Line.Info info)
Return a line matching the provided description.
static Mixer
getMixer(Mixer.Info info)
Return a mixer matching the provided description.
static Mixer.Info[]
getMixerInfo()
Return an array of descriptions of all the mixers provided on the system.
static SourceDataLine
getSourceDataLine(AudioFormat fmt)
Return a source data line matching the given audio format.
static SourceDataLine
getSourceDataLine(AudioFormat fmt, Mixer.Info mixer)
Return a target data line matching the given audio format.
static Line.Info[]
getSourceLineInfo(Line.Info info)
Return an array of descriptions of all the source lines matching the given line description.
static TargetDataLine
getTargetDataLine(AudioFormat fmt)
Find and return a target data line matching the given audio format.
static TargetDataLine
getTargetDataLine(AudioFormat fmt, Mixer.Info mixer)
Return a target data line matching the given audio format and mixer.
static AudioFormat.Encoding[]
getTargetEncodings(AudioFormat source)
Given a source format, return an array of all the target encodings to which data in this format can be converted.
static AudioFormat.Encoding[]
getTargetEncodings(AudioFormat.Encoding source)
Given a source encoding, return an array of all target encodings to which data in this form can be converted.
static AudioFormat[]
getTargetFormats(AudioFormat.Encoding encoding, AudioFormat sourceFmt)
Given a target encoding and a source audio format, return an array of all matching audio formats to which data in this source format can be converted.
static Line.Info[]
getTargetLineInfo(Line.Info info)
Given a line description, return an array of descriptions of all the matching target lines.
static boolean
isConversionSupported(AudioFormat targ, AudioFormat source)
Return true if the currently installed providers are able to convert the given source format to the given target format.
static boolean
isConversionSupported(AudioFormat.Encoding targ, AudioFormat source)
Return true if the currently installed providers are able to convert data from the given source format to the given target encoding.
static boolean
isFileTypeSupported(AudioFileFormat.Type type)
Return true if the given audio file format is supported by one of the providers installed on the system.
static boolean
isFileTypeSupported(AudioFileFormat.Type type, AudioInputStream ais)
Return true if the given audio file format is supported for the given audio input stream by one of the providers installed on the system.
static boolean
isLineSupported(Line.Info info)
Return true if some provider on the system supplies a line matching the argument.
static int
write(AudioInputStream ais, AudioFileFormat.Type type, File out)
Write an audio input stream to the given file, using the specified audio file format.
static int
write(AudioInputStream ais, AudioFileFormat.Type type, OutputStream os)
Write an audio input stream to the given output stream, using the specified audio file format.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

NOT_SPECIFIED

public static final int NOT_SPECIFIED
A constant which can be passed to a number of methods in this package, to indicate an unspecified value.
Field Value:
-1

Method Details

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(File f)
            throws UnsupportedAudioFileException,
                   IOException
Return the file format of a given File.
Parameters:
f - the file to check
Returns:
the format of the file
Throws:
UnsupportedAudioFileException - if the file's format is not recognized
IOException - if there is an I/O error reading the file

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(InputStream is)
            throws UnsupportedAudioFileException,
                   IOException
Return the file format of a given input stream.
Parameters:
is - the input stream to check
Returns:
the format of the stream
Throws:
UnsupportedAudioFileException - if the stream's format is not recognized
IOException - if there is an I/O error reading the stream

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(URL url)
            throws UnsupportedAudioFileException,
                   IOException
Return the file format of a given URL.
Parameters:
url - the URL to check
Returns:
the format of the URL
Throws:
UnsupportedAudioFileException - if the URL's format is not recognized
IOException - if there is an I/O error reading the URL

getAudioFileTypes

public static AudioFileFormat.Type[] getAudioFileTypes()
Return an array of all the supported AudioFileFormat types.
Returns:
an array of unique types

getAudioFileTypes

public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream ais)
Return an array of all the supported AudioFileFormat types which match the given audio input stream
Parameters:
ais - the audio input stream
Returns:
an array of unique types

getAudioInputStream

public static AudioInputStream getAudioInputStream(File f)
            throws UnsupportedAudioFileException,
                   IOException
Return an audio input stream for the file.
Parameters:
f - the file to read
Returns:
an audio input stream for the file
Throws:
UnsupportedAudioFileException - if the file's audio format is not recognized
IOException - if there is an error while reading the file

getAudioInputStream

public static AudioInputStream getAudioInputStream(InputStream is)
            throws UnsupportedAudioFileException,
                   IOException
Return an audio input stream given an input stream.
Parameters:
is - the input stream
Returns:
an audio input stream
Throws:
UnsupportedAudioFileException - if the input stream's audio format is not supported by any of the installed providers
IOException - if there is an error while reading the input stream

getAudioInputStream

public static AudioInputStream getAudioInputStream(URL url)
            throws UnsupportedAudioFileException,
                   IOException
Return an audio input stream for the given URL.
Parameters:
url - the URL
Returns:
an audio input stream
Throws:
UnsupportedAudioFileException - if the URL's audio format is not supported by any of the installed providers
IOException - if there is an error while reading the URL

getAudioInputStream

public static AudioInputStream getAudioInputStream(AudioFormat targ,
                                                   AudioInputStream ais)
Given an audio input stream, this will try to create a new audio input stream whose format matches the given target format. If no provider offers this conversion, an exception is thrown.
Parameters:
targ - the target format
ais - the original audio stream
Returns:
a new audio stream
Throws:
IllegalArgumentException - if the conversion cannot be made

getAudioInputStream

public static AudioInputStream getAudioInputStream(AudioFormat.Encoding targ,
                                                   AudioInputStream ais)
Given an audio input stream, this will try to create a new audio input stream whose encoding matches the given target encoding. If no provider offers this conversion, an exception is thrown.
Parameters:
targ - the target encoding
ais - the original audio stream
Returns:
a new audio stream
Throws:
IllegalArgumentException - if the conversion cannot be made

getClip

public static Clip getClip()
            throws LineUnavailableException
Return a new clip which can be used for playing back an audio stream.
Throws:
LineUnavailableException - if a clip is not available for some reason
SecurityException - if a clip cannot be made for security reasons
Since:
1.5

getClip

public static Clip getClip(Mixer.Info info)
            throws LineUnavailableException
Return a new clip which can be used for playing back an audio stream. The clip is obtained from the indicated mixer.
Parameters:
info - the mixer to use
Throws:
LineUnavailableException - if a clip is not available for some reason
SecurityException - if a clip cannot be made for security reasons
Since:
1.5

getLine

public static Line getLine(Line.Info info)
            throws LineUnavailableException
Return a line matching the provided description. All the providers on the system are searched for a matching line.
Parameters:
info - description of the line
Returns:
the matching line
Throws:
LineUnavailableException - if no provider supplies a matching line

getMixer

public static Mixer getMixer(Mixer.Info info)
Return a mixer matching the provided description. All the providers on the system are searched for a matching mixer.
Parameters:
info - description of the mixer
Returns:
the matching mixer
Throws:
IllegalArgumentException - if no provider supplies a matching mixer

getMixerInfo

public static Mixer.Info[] getMixerInfo()
Return an array of descriptions of all the mixers provided on the system.

getSourceDataLine

public static SourceDataLine getSourceDataLine(AudioFormat fmt)
            throws LineUnavailableException
Return a source data line matching the given audio format.
Parameters:
fmt - the audio format
Throws:
LineUnavailableException - if no source data line matching this format is available
Since:
1.5

getSourceDataLine

public static SourceDataLine getSourceDataLine(AudioFormat fmt,
                                               Mixer.Info mixer)
            throws LineUnavailableException
Return a target data line matching the given audio format.
Parameters:
fmt - the audio format
Throws:
LineUnavailableException - if no target data line matching this format is available
Since:
1.5

getSourceLineInfo

public static Line.Info[] getSourceLineInfo(Line.Info info)
Return an array of descriptions of all the source lines matching the given line description.
Parameters:
info - description of the lines to match

getTargetDataLine

public static TargetDataLine getTargetDataLine(AudioFormat fmt)
            throws LineUnavailableException
Find and return a target data line matching the given audio format.
Parameters:
fmt - the format to match
Throws:
LineUnavailableException - if no matching line was found
Since:
1.5

getTargetDataLine

public static TargetDataLine getTargetDataLine(AudioFormat fmt,
                                               Mixer.Info mixer)
            throws LineUnavailableException
Return a target data line matching the given audio format and mixer.
Parameters:
fmt - the audio format
mixer - the mixer description
Returns:
a target data line
Throws:
LineUnavailableException - if no matching target data line was found
Since:
1.5

getTargetEncodings

public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat source)
Given a source format, return an array of all the target encodings to which data in this format can be converted.
Parameters:
source - the source format

getTargetEncodings

public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding source)
Given a source encoding, return an array of all target encodings to which data in this form can be converted.
Parameters:
source - the source encoding

getTargetFormats

public static AudioFormat[] getTargetFormats(AudioFormat.Encoding encoding,
                                             AudioFormat sourceFmt)
Given a target encoding and a source audio format, return an array of all matching audio formats to which data in this source format can be converted.
Parameters:
encoding - the target encoding
sourceFmt - the source format

getTargetLineInfo

public static Line.Info[] getTargetLineInfo(Line.Info info)
Given a line description, return an array of descriptions of all the matching target lines.
Parameters:
info - the line description

isConversionSupported

public static boolean isConversionSupported(AudioFormat targ,
                                            AudioFormat source)
Return true if the currently installed providers are able to convert the given source format to the given target format.
Parameters:
targ - the target format
source - the source format

isConversionSupported

public static boolean isConversionSupported(AudioFormat.Encoding targ,
                                            AudioFormat source)
Return true if the currently installed providers are able to convert data from the given source format to the given target encoding.
Parameters:
targ - the target encoding
source - the source format

isFileTypeSupported

public static boolean isFileTypeSupported(AudioFileFormat.Type type)
Return true if the given audio file format is supported by one of the providers installed on the system.
Parameters:
type - the audio file format type

isFileTypeSupported

public static boolean isFileTypeSupported(AudioFileFormat.Type type,
                                          AudioInputStream ais)
Return true if the given audio file format is supported for the given audio input stream by one of the providers installed on the system.
Parameters:
type - the audio file format type
ais - the audio input stream

isLineSupported

public static boolean isLineSupported(Line.Info info)
Return true if some provider on the system supplies a line matching the argument.
Parameters:
info - the line to match

write

public static int write(AudioInputStream ais,
                        AudioFileFormat.Type type,
                        File out)
            throws IOException
Write an audio input stream to the given file, using the specified audio file format. All the providers installed on the system will be searched to find one that supports this operation.
Parameters:
ais - the audio input stream to write
type - the desired audio file format type
out - the file to write to
Returns:
the number of bytes written
Throws:
IOException - if an I/O error occurs while writing
IllegalArgumentException - if the file type is not supported

write

public static int write(AudioInputStream ais,
                        AudioFileFormat.Type type,
                        OutputStream os)
            throws IOException
Write an audio input stream to the given output stream, using the specified audio file format. All the providers installed on the system will be searched to find one that supports this operation.
Parameters:
ais - the audio input stream to write
type - the desired audio file format type
os - the output stream to write to
Returns:
the number of bytes written
Throws:
IOException - if an I/O error occurs while writing
IllegalArgumentException - if the file type is not supported

Main interface to audio system Copyright (C) 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.