Back to index...

	/*
	* Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code 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
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package javax.sound.sampled;

	import java.util.Collections;
	import java.util.HashMap;
	import java.util.Map;

	/**
	* <code>AudioFormat</code> is the class that specifies a particular arrangement of data in a sound stream.
	* By examining the information stored in the audio format, you can discover how to interpret the bits in the
	* binary sound data.
	* <p>
	* Every data line has an audio format associated with its data stream. The audio format of a source (playback) data line indicates
	* what kind of data the data line expects to receive for output. For a target (capture) data line, the audio format specifies the kind
	* of the data that can be read from the line.
	* Sound files also have audio formats, of course. The <code>{@link AudioFileFormat}</code>
	* class encapsulates an <code>AudioFormat</code> in addition to other,
	* file-specific information. Similarly, an <code>{@link AudioInputStream}</code> has an
	* <code>AudioFormat</code>.
	* <p>
	* The <code>AudioFormat</code> class accommodates a number of common sound-file encoding techniques, including
	* pulse-code modulation (PCM), mu-law encoding, and a-law encoding. These encoding techniques are predefined,
	* but service providers can create new encoding types.
	* The encoding that a specific format uses is named by its <code>encoding</code> field.
	*<p>
	* In addition to the encoding, the audio format includes other properties that further specify the exact
	* arrangement of the data.
	* These include the number of channels, sample rate, sample size, byte order, frame rate, and frame size.
	* Sounds may have different numbers of audio channels: one for mono, two for stereo.
	* The sample rate measures how many "snapshots" (samples) of the sound pressure are taken per second, per channel.
	* (If the sound is stereo rather than mono, two samples are actually measured at each instant of time: one for the left channel,
	* and another for the right channel; however, the sample rate still measures the number per channel, so the rate is the same
	* regardless of the number of channels. This is the standard use of the term.)
	* The sample size indicates how many bits are used to store each snapshot; 8 and 16 are typical values.
	* For 16-bit samples (or any other sample size larger than a byte),
	* byte order is important; the bytes in each sample are arranged in
	* either the "little-endian" or "big-endian" style.
	* For encodings like PCM, a frame consists of the set of samples for all channels at a given
	* point in time, and so the size of a frame (in bytes) is always equal to the size of a sample (in bytes) times
	* the number of channels. However, with some other sorts of encodings a frame can contain
	* a bundle of compressed data for a whole series of samples, as well as additional, non-sample
	* data. For such encodings, the sample rate and sample size refer to the data after it is decoded into PCM,
	* and so they are completely different from the frame rate and frame size.
	*
	* <p>An <code>AudioFormat</code> object can include a set of
	* properties. A property is a pair of key and value: the key
	* is of type <code>String</code>, the associated property
	* value is an arbitrary object. Properties specify
	* additional format specifications, like the bit rate for
	* compressed formats. Properties are mainly used as a means
	* to transport additional information of the audio format
	* to and from the service providers. Therefore, properties
	* are ignored in the {@link #matches(AudioFormat)} method.
	* However, methods which rely on the installed service
	* providers, like {@link AudioSystem#isConversionSupported
	* (AudioFormat, AudioFormat) isConversionSupported} may consider
	* properties, depending on the respective service provider
	* implementation.
	*
	* <p>The following table lists some common properties which
	* service providers should use, if applicable:
	*
	* <table border=0>
	* <caption>Audio Format Properties</caption>
	* <tr>
	* <th>Property key</th>
	* <th>Value type</th>
	* <th>Description</th>
	* </tr>
	* <tr>
	* <td>"bitrate"</td>
	* <td>{@link java.lang.Integer Integer}</td>
	* <td>average bit rate in bits per second</td>
	* </tr>
	* <tr>
	* <td>"vbr"</td>
	* <td>{@link java.lang.Boolean Boolean}</td>
	* <td><code>true</code>, if the file is encoded in variable bit
	* rate (VBR)</td>
	* </tr>
	* <tr>
	* <td>"quality"</td>
	* <td>{@link java.lang.Integer Integer}</td>
	* <td>encoding/conversion quality, 1..100</td>
	* </tr>
	* </table>
	*
	* <p>Vendors of service providers (plugins) are encouraged
	* to seek information about other already established
	* properties in third party plugins, and follow the same
	* conventions.
	*
	* @author Kara Kytle
	* @author Florian Bomers
	* @see DataLine#getFormat
	* @see AudioInputStream#getFormat
	* @see AudioFileFormat
	* @see javax.sound.sampled.spi.FormatConversionProvider
	* @since 1.3
	*/
	public class AudioFormat {

	// INSTANCE VARIABLES


	/**
	* The audio encoding technique used by this format.
	*/
	protected Encoding encoding;

	/**
	* The number of samples played or recorded per second, for sounds that have this format.
	*/
	protected float sampleRate;

	/**
	* The number of bits in each sample of a sound that has this format.
	*/
	protected int sampleSizeInBits;

	/**
	* The number of audio channels in this format (1 for mono, 2 for stereo).
	*/
	protected int channels;

	/**
	* The number of bytes in each frame of a sound that has this format.
	*/
	protected int frameSize;

	/**
	* The number of frames played or recorded per second, for sounds that have this format.
	*/
	protected float frameRate;

	/**
	* Indicates whether the audio data is stored in big-endian or little-endian order.
	*/
	protected boolean bigEndian;


	/** The set of properties */
	private HashMap<String, Object> properties;


	/**
	* Constructs an <code>AudioFormat</code> with the given parameters.
	* The encoding specifies the convention used to represent the data.
	* The other parameters are further explained in the {@link AudioFormat
	* class description}.
	* @param encoding the audio encoding technique
	* @param sampleRate the number of samples per second
	* @param sampleSizeInBits the number of bits in each sample
	* @param channels the number of channels (1 for mono, 2 for stereo, and so on)
	* @param frameSize the number of bytes in each frame
	* @param frameRate the number of frames per second
	* @param bigEndian indicates whether the data for a single sample
	* is stored in big-endian byte order (<code>false</code>
	* means little-endian)
	*/
	public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
	int channels, int frameSize, float frameRate, boolean bigEndian) {

	this.encoding = encoding;
	this.sampleRate = sampleRate;
	this.sampleSizeInBits = sampleSizeInBits;
	this.channels = channels;
	this.frameSize = frameSize;
	this.frameRate = frameRate;
	this.bigEndian = bigEndian;
	this.properties = null;
	}


	/**
	* Constructs an <code>AudioFormat</code> with the given parameters.
	* The encoding specifies the convention used to represent the data.
	* The other parameters are further explained in the {@link AudioFormat
	* class description}.
	* @param encoding the audio encoding technique
	* @param sampleRate the number of samples per second
	* @param sampleSizeInBits the number of bits in each sample
	* @param channels the number of channels (1 for mono, 2 for
	* stereo, and so on)
	* @param frameSize the number of bytes in each frame
	* @param frameRate the number of frames per second
	* @param bigEndian indicates whether the data for a single sample
	* is stored in big-endian byte order
	* (<code>false</code> means little-endian)
	* @param properties a <code>Map<String,Object></code> object
	* containing format properties
	*
	* @since 1.5
	*/
	public AudioFormat(Encoding encoding, float sampleRate,
	int sampleSizeInBits, int channels,
	int frameSize, float frameRate,
	boolean bigEndian, Map<String, Object> properties) {
	this(encoding, sampleRate, sampleSizeInBits, channels,
	frameSize, frameRate, bigEndian);
	this.properties = new HashMap<String, Object>(properties);
	}


	/**
	* Constructs an <code>AudioFormat</code> with a linear PCM encoding and
	* the given parameters. The frame size is set to the number of bytes
	* required to contain one sample from each channel, and the frame rate
	* is set to the sample rate.
	*
	* @param sampleRate the number of samples per second
	* @param sampleSizeInBits the number of bits in each sample
	* @param channels the number of channels (1 for mono, 2 for stereo, and so on)
	* @param signed indicates whether the data is signed or unsigned
	* @param bigEndian indicates whether the data for a single sample
	* is stored in big-endian byte order (<code>false</code>
	* means little-endian)
	*/
	public AudioFormat(float sampleRate, int sampleSizeInBits,
	int channels, boolean signed, boolean bigEndian) {

	this((signed == true ? Encoding.PCM_SIGNED : Encoding.PCM_UNSIGNED),
	sampleRate,
	sampleSizeInBits,
	channels,
	(channels == AudioSystem.NOT_SPECIFIED \|\| sampleSizeInBits == AudioSystem.NOT_SPECIFIED)?
	AudioSystem.NOT_SPECIFIED:
	((sampleSizeInBits + 7) / 8) * channels,
	sampleRate,
	bigEndian);
	}

	/**
	* Obtains the type of encoding for sounds in this format.
	*
	* @return the encoding type
	* @see Encoding#PCM_SIGNED
	* @see Encoding#PCM_UNSIGNED
	* @see Encoding#ULAW
	* @see Encoding#ALAW
	*/
	public Encoding getEncoding() {

	return encoding;
	}

	/**
	* Obtains the sample rate.
	* For compressed formats, the return value is the sample rate of the uncompressed
	* audio data.
	* When this AudioFormat is used for queries (e.g. {@link
	* AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
	* AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
	* DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample rate of
	* <code>AudioSystem.NOT_SPECIFIED</code> means that any sample rate is
	* acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
	* the sample rate is not defined for this audio format.
	* @return the number of samples per second,
	* or <code>AudioSystem.NOT_SPECIFIED</code>
	*
	* @see #getFrameRate()
	* @see AudioSystem#NOT_SPECIFIED
	*/
	public float getSampleRate() {

	return sampleRate;
	}

	/**
	* Obtains the size of a sample.
	* For compressed formats, the return value is the sample size of the
	* uncompressed audio data.
	* When this AudioFormat is used for queries (e.g. {@link
	* AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
	* AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
	* DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample size of
	* <code>AudioSystem.NOT_SPECIFIED</code> means that any sample size is
	* acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
	* the sample size is not defined for this audio format.
	* @return the number of bits in each sample,
	* or <code>AudioSystem.NOT_SPECIFIED</code>
	*
	* @see #getFrameSize()
	* @see AudioSystem#NOT_SPECIFIED
	*/
	public int getSampleSizeInBits() {

	return sampleSizeInBits;
	}

	/**
	* Obtains the number of channels.
	* When this AudioFormat is used for queries (e.g. {@link
	* AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
	* AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
	* DataLine.Info#getFormats() DataLine.Info.getFormats}), a return value of
	* <code>AudioSystem.NOT_SPECIFIED</code> means that any (positive) number of channels is
	* acceptable.
	* @return The number of channels (1 for mono, 2 for stereo, etc.),
	* or <code>AudioSystem.NOT_SPECIFIED</code>
	*
	* @see AudioSystem#NOT_SPECIFIED
	*/
	public int getChannels() {

	return channels;
	}

	/**
	* Obtains the frame size in bytes.
	* When this AudioFormat is used for queries (e.g. {@link
	* AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
	* AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
	* DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame size of
	* <code>AudioSystem.NOT_SPECIFIED</code> means that any frame size is
	* acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
	* the frame size is not defined for this audio format.
	* @return the number of bytes per frame,
	* or <code>AudioSystem.NOT_SPECIFIED</code>
	*
	* @see #getSampleSizeInBits()
	* @see AudioSystem#NOT_SPECIFIED
	*/
	public int getFrameSize() {

	return frameSize;
	}

	/**
	* Obtains the frame rate in frames per second.
	* When this AudioFormat is used for queries (e.g. {@link
	* AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
	* AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
	* DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame rate of
	* <code>AudioSystem.NOT_SPECIFIED</code> means that any frame rate is
	* acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
	* the frame rate is not defined for this audio format.
	* @return the number of frames per second,
	* or <code>AudioSystem.NOT_SPECIFIED</code>
	*
	* @see #getSampleRate()
	* @see AudioSystem#NOT_SPECIFIED
	*/
	public float getFrameRate() {

	return frameRate;
	}


	/**
	* Indicates whether the audio data is stored in big-endian or little-endian
	* byte order. If the sample size is not more than one byte, the return value is
	* irrelevant.
	* @return <code>true</code> if the data is stored in big-endian byte order,
	* <code>false</code> if little-endian
	*/
	public boolean isBigEndian() {

	return bigEndian;
	}


	/**
	* Obtain an unmodifiable map of properties.
	* The concept of properties is further explained in
	* the {@link AudioFileFormat class description}.
	*
	* @return a <code>Map<String,Object></code> object containing
	* all properties. If no properties are recognized, an empty map is
	* returned.
	*
	* @see #getProperty(String)
	* @since 1.5
	*/
	public Map<String,Object> properties() {
	Map<String,Object> ret;
	if (properties == null) {
	ret = new HashMap<String,Object>(0);
	} else {
	ret = (Map<String,Object>) (properties.clone());
	}
	return (Map<String,Object>) Collections.unmodifiableMap(ret);
	}


	/**
	* Obtain the property value specified by the key.
	* The concept of properties is further explained in
	* the {@link AudioFileFormat class description}.
	*
	* <p>If the specified property is not defined for a
	* particular file format, this method returns
	* <code>null</code>.
	*
	* @param key the key of the desired property
	* @return the value of the property with the specified key,
	* or <code>null</code> if the property does not exist.
	*
	* @see #properties()
	* @since 1.5
	*/
	public Object getProperty(String key) {
	if (properties == null) {
	return null;
	}
	return properties.get(key);
	}


	/**
	* Indicates whether this format matches the one specified.
	* To match, two formats must have the same encoding,
	* and consistent values of the number of channels, sample rate, sample size,
	* frame rate, and frame size.
	* The values of the property are consistent if they are equal
	* or the specified format has the property value
	* {@code AudioSystem.NOT_SPECIFIED}.
	* The byte order (big-endian or little-endian) must be the same
	* if the sample size is greater than one byte.
	*
	* @param format format to test for match
	* @return {@code true} if this format matches the one specified,
	* {@code false} otherwise.
	*/
	public boolean matches(AudioFormat format) {
	if (format.getEncoding().equals(getEncoding())
	&& (format.getChannels() == AudioSystem.NOT_SPECIFIED
	\|\| format.getChannels() == getChannels())
	&& (format.getSampleRate() == (float)AudioSystem.NOT_SPECIFIED
	\|\| format.getSampleRate() == getSampleRate())
	&& (format.getSampleSizeInBits() == AudioSystem.NOT_SPECIFIED
	\|\| format.getSampleSizeInBits() == getSampleSizeInBits())
	&& (format.getFrameRate() == (float)AudioSystem.NOT_SPECIFIED
	\|\| format.getFrameRate() == getFrameRate())
	&& (format.getFrameSize() == AudioSystem.NOT_SPECIFIED
	\|\| format.getFrameSize() == getFrameSize())
	&& (getSampleSizeInBits() <= 8
	\|\| format.isBigEndian() == isBigEndian())) {
	return true;
	}
	return false;
	}


	/**
	* Returns a string that describes the format, such as:
	* "PCM SIGNED 22050 Hz 16 bit mono big-endian". The contents of the string
	* may vary between implementations of Java Sound.
	*
	* @return a string that describes the format parameters
	*/
	public String toString() {
	String sEncoding = "";
	if (getEncoding() != null) {
	sEncoding = getEncoding().toString() + " ";
	}

	String sSampleRate;
	if (getSampleRate() == (float) AudioSystem.NOT_SPECIFIED) {
	sSampleRate = "unknown sample rate, ";
	} else {
	sSampleRate = "" + getSampleRate() + " Hz, ";
	}

	String sSampleSizeInBits;
	if (getSampleSizeInBits() == (float) AudioSystem.NOT_SPECIFIED) {
	sSampleSizeInBits = "unknown bits per sample, ";
	} else {
	sSampleSizeInBits = "" + getSampleSizeInBits() + " bit, ";
	}

	String sChannels;
	if (getChannels() == 1) {
	sChannels = "mono, ";
	} else
	if (getChannels() == 2) {
	sChannels = "stereo, ";
	} else {
	if (getChannels() == AudioSystem.NOT_SPECIFIED) {
	sChannels = " unknown number of channels, ";
	} else {
	sChannels = ""+getChannels()+" channels, ";
	}
	}

	String sFrameSize;
	if (getFrameSize() == (float) AudioSystem.NOT_SPECIFIED) {
	sFrameSize = "unknown frame size, ";
	} else {
	sFrameSize = "" + getFrameSize()+ " bytes/frame, ";
	}

	String sFrameRate = "";
	if (Math.abs(getSampleRate() - getFrameRate()) > 0.00001) {
	if (getFrameRate() == (float) AudioSystem.NOT_SPECIFIED) {
	sFrameRate = "unknown frame rate, ";
	} else {
	sFrameRate = getFrameRate() + " frames/second, ";
	}
	}

	String sEndian = "";
	if ((getEncoding().equals(Encoding.PCM_SIGNED)
	\|\| getEncoding().equals(Encoding.PCM_UNSIGNED))
	&& ((getSampleSizeInBits() > 8)
	\|\| (getSampleSizeInBits() == AudioSystem.NOT_SPECIFIED))) {
	if (isBigEndian()) {
	sEndian = "big-endian";
	} else {
	sEndian = "little-endian";
	}
	}

	return sEncoding
	+ sSampleRate
	+ sSampleSizeInBits
	+ sChannels
	+ sFrameSize
	+ sFrameRate
	+ sEndian;

	}

	/**
	* The <code>Encoding</code> class names the specific type of data representation
	* used for an audio stream. The encoding includes aspects of the
	* sound format other than the number of channels, sample rate, sample size,
	* frame rate, frame size, and byte order.
	* <p>
	* One ubiquitous type of audio encoding is pulse-code modulation (PCM),
	* which is simply a linear (proportional) representation of the sound
	* waveform. With PCM, the number stored in each sample is proportional
	* to the instantaneous amplitude of the sound pressure at that point in
	* time. The numbers may be signed or unsigned integers or floats.
	* Besides PCM, other encodings include mu-law and a-law, which are nonlinear
	* mappings of the sound amplitude that are often used for recording speech.
	* <p>
	* You can use a predefined encoding by referring to one of the static
	* objects created by this class, such as PCM_SIGNED or
	* PCM_UNSIGNED. Service providers can create new encodings, such as
	* compressed audio formats, and make
	* these available through the <code>{@link AudioSystem}</code> class.
	* <p>
	* The <code>Encoding</code> class is static, so that all
	* <code>AudioFormat</code> objects that have the same encoding will refer
	* to the same object (rather than different instances of the same class).
	* This allows matches to be made by checking that two format's encodings
	* are equal.
	*
	* @see AudioFormat
	* @see javax.sound.sampled.spi.FormatConversionProvider
	*
	* @author Kara Kytle
	* @since 1.3
	*/
	public static class Encoding {


	// ENCODING DEFINES

	/**
	* Specifies signed, linear PCM data.
	*/
	public static final Encoding PCM_SIGNED = new Encoding("PCM_SIGNED");

	/**
	* Specifies unsigned, linear PCM data.
	*/
	public static final Encoding PCM_UNSIGNED = new Encoding("PCM_UNSIGNED");

	/**
	* Specifies floating-point PCM data.
	*
	* @since 1.7
	*/
	public static final Encoding PCM_FLOAT = new Encoding("PCM_FLOAT");

	/**
	* Specifies u-law encoded data.
	*/
	public static final Encoding ULAW = new Encoding("ULAW");

	/**
	* Specifies a-law encoded data.
	*/
	public static final Encoding ALAW = new Encoding("ALAW");


	// INSTANCE VARIABLES

	/**
	* Encoding name.
	*/
	private String name;


	// CONSTRUCTOR

	/**
	* Constructs a new encoding.
	* @param name the name of the new type of encoding
	*/
	public Encoding(String name) {
	this.name = name;
	}


	// METHODS

	/**
	* Finalizes the equals method
	*/
	public final boolean equals(Object obj) {
	if (toString() == null) {
	return (obj != null) && (obj.toString() == null);
	}
	if (obj instanceof Encoding) {
	return toString().equals(obj.toString());
	}
	return false;
	}

	/**
	* Finalizes the hashCode method
	*/
	public final int hashCode() {
	if (toString() == null) {
	return 0;
	}
	return toString().hashCode();
	}

	/**
	* Provides the <code>String</code> representation of the encoding. This <code>String</code> is
	* the same name that was passed to the constructor. For the predefined encodings, the name
	* is similar to the encoding's variable (field) name. For example, <code>PCM_SIGNED.toString()</code> returns
	* the name "pcm_signed".
	*
	* @return the encoding name
	*/
	public final String toString() {
	return name;
	}

	} // class Encoding
	}

Back to index...