Package ptolemy.media.javasound

Class SoundReader

java.lang.Object

ptolemy.media.javasound.SoundReader

public class SoundReader
extends java.lang.Object

This class is a buffer that supports the reading of audio samples from a sound file that is specified as a URL. Specifically, this buffer supports the reading of double-valued audio samples. The maximum valid range of sample values is from -1.0 to 1.0. Any values outside of this range will be hard-clipped to fall within this range.

Supported file types

Valid sound file formats are WAVE (.wav), AIFF (.aif, .aiff), AU (.au). Valid sample rates are 8000, 11025, 22050, 44100, and 48000 Hz. Both 8 bit and 16 bit audio are supported. Mono and stereo files are supported.

Usage

The path to the sound file, specified as a URL, is given as a constructor parameter. The constructor also takes an array length parameter, which is explained below. The constructor will attempt to open the specified file.

After invoking the constructor, the getSamples() method should be repeatedly invoked to read samples from the specified sound file. The getSamples() method takes a multidimensional array as a parameter. The first index represents the channel number (0 for first channel, 1 for second channel, etc.). The second index represents the sample index within a channel. For each channel i, the size of the array, getSamplesArray[i].length, must be equal to the constructor parameter getSamplesArraySize. Otherwise an exception will occur. When the end of the sound file is reached, this method will return null.

The getChannels(), getSampleRate(), and getBitsPerSample() methods may be invoked at any time to obtain information about the format of the sound file.

When no more samples are desired, the closeFile() method should be invoked to close the sound file. An exception will occur if getSamples() is invoked at any point after closeFile() is invoked.

Security Issues

Applications have no restrictions on the capturing or playback of audio. Applets, however, may by default only capture audio from a file specified as a URL on the same machine as the one the applet was loaded from. Applet code is not allowed to read or write native files. The .java.policy file may be modified to grant applets more privileges.

Note: Requires Java 2 v1.3.0 or later.

Since:

Ptolemy II 1.0

Version:

$Id$

Author:

Brian K. Vogel

See Also:

SoundWriter

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

Red (vogel)

Constructor Summary

Constructors

Constructor	Description
SoundReader(java.lang.String sourceURL, int getSamplesArraySize)	Construct a sound reader object that reads audio samples from a sound file specified as a string describing a URL and open the file at the specified URL.
SoundReader(java.net.URL soundURL, int getSamplesArraySize)	Construct a sound reader object that reads audio samples from a sound file specified as a URL and open the file at the specified URL.

Method Summary

Modifier and Type	Method	Description
void	closeFile()	Close the file at the specified URL.
int	getBitsPerSample()	Return the number of bits per audio sample.
int	getChannels()	Return the number of audio channels.
float	getSampleRate()	Return the sampling rate in Hz.
double[][]	getSamples()	Return an array of captured audio samples.

Methods inherited from class java.lang.Object

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

Constructor Detail

SoundReader

public SoundReader(java.lang.String sourceURL,
                   int getSamplesArraySize)
            throws java.io.IOException

Construct a sound reader object that reads audio samples from a sound file specified as a string describing a URL and open the file at the specified URL. For example, to capture samples from the URL http://localhost/soundfile.wav, sourceURL should be set to the string "http://localhost/soundfile.wav" Note that the "http://" is required. Note that it is still possible to capture audio from a file on the local file system. For example, to capture from a sound file located at "C:\someDir\someFile.wave", sourceURL should be set to "file:c:\someDir\someFile.wave". Relative file paths are not supported, so the complete path must always be specified, using the prefix "file:" It is safe to call getSamples() immediately after this constructor returns.

Parameters:

sourceURL - A string describing a URL.

getSamplesArraySize - The number of samples per channel returned by getSamples().

Throws:

java.io.IOException - If opening the sourceURL throws it, if the file format is not supported or if there is no audio to play.

SoundReader

public SoundReader(java.net.URL soundURL,
                   int getSamplesArraySize)
            throws java.io.IOException

Construct a sound reader object that reads audio samples from a sound file specified as a URL and open the file at the specified URL. It is safe to call getSamples() immediately after this constructor returns.

Parameters:

soundURL - The URL of a sound file.

getSamplesArraySize - The number of samples per channel returned by getSamples().

Throws:

java.io.IOException - If opening the sourceURL throws it, if the file format is not supported or if there is no audio to play.

Method Detail

getChannels

public int getChannels()
                throws java.lang.IllegalStateException

Return the number of audio channels. This method should be called while the file is open (i.e., before closeFile() is called). Otherwise an exception will occur.

Returns:

The number of audio channels.

Throws:

java.lang.IllegalStateException - If this method is called before openFile() is called or after closeFile() is called.

getSampleRate

public float getSampleRate()
                    throws java.lang.IllegalStateException

Return the sampling rate in Hz. An exception will occur if this method is invoked after closeFile() is called.

Returns:

The sample rate in Hz.

Throws:

java.lang.IllegalStateException - If this method is called after closeFile() is called.

getSamples

public double[][] getSamples()
                      throws java.io.IOException,
                             java.lang.IllegalStateException

Return an array of captured audio samples. This method should be repeatedly called to obtain audio data. The returned audio samples will have values in the range [-1, 1], regardless of the audio bit resolution (bits per sample). This method performs a blocking read, so it is not possible to invoke this method too frequently.

The array size is set by the getSamplesSize parameter in the constructor.

Returns:

Two dimensional array of captured audio samples. Return null if end of the audio file is reached. The first index represents the channel number (0 for first channel, 1 for second channel, etc.). The second index represents the sample index within a channel. For example, returned array[n][m] contains the (m+1)th sample of the (n+1)th channel. For each channel, n, the length of returned array[n] is equal to getSamplesSize.

Throws:

java.io.IOException - If there is a problem reading the audio samples from the input file.

java.lang.IllegalStateException - If closeFile() has already been called.

closeFile

public void closeFile()
               throws java.io.IOException

Close the file at the specified URL. This method should be called when no more calls to getSamples(). are required.

Throws:

java.io.IOException - If there is a problem closing the file.

getBitsPerSample

public int getBitsPerSample()
                     throws java.lang.IllegalStateException

Return the number of bits per audio sample. An exception will occur if this method is called after closeFile() is invoked.

Returns:

The sample size in bits.

Throws:

java.lang.IllegalStateException - If this method is called after closeFile() is called.