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.

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	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)

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.

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

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 Clip	getClip () Obtains a clip that can be used for playing back an audio file or an audio stream.
static Clip	getClip (Mixer.Info mixerInfo) Obtains a clip from the specified mixer that can be used for playing back an audio file or an audio stream.
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 SourceDataLine	getSourceDataLine (AudioFormat format) 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 (AudioFormat format, Mixer.Info mixerinfo) 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 (Line.Info info) Obtains information about all source lines of a particular type that are supported by the installed mixers.
static TargetDataLine	getTargetDataLine (AudioFormat format) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object.
static TargetDataLine	getTargetDataLine (AudioFormat format, Mixer.Info mixerinfo) 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 (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 all target lines of a particular type that are supported by the installed mixers.
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 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.

See Also:

Constant Field Values

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