Package ptolemy.media.javasound

Class SoundWriter

java.lang.Object

ptolemy.media.javasound.SoundWriter

public class SoundWriter
extends java.lang.Object

This class is a buffer that supports the writing of audio samples to a sound file. Specifically, this buffer supports the writing 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 to write is given as a constructor parameter, along with parameters that specify the desired audio format. The constructor also takes an array length parameter, which is explained below.

After invoking the constructor, the putSamples() method should be repeatedly invoked to write samples to the specified sound file. This method is blocking, so it will not return until the samples have been written. The putSamples() 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, putSamplesArray[i].length, must be equal to the constructor parameter putSamplesArraySize. Otherwise an exception will occur. Thus, each call to putSamples() writes putSamplesArraySize on each channel. It should be noted that the putSamples() method does not write samples directly to a sound file, but instead writes samples to an internal array. The internal array of samples is written to the sound file by the closeFile() method.

The closeFile() method should be invoked when no more samples need to be written. This method will write the internal array of samples to the output file and close the file. It is not possible to write any more samples after closeFile() has been called. An exception will occur if putSamples() is invoked at any point after closeFile() is invoked.

Security issues

Applications have no restrictions on the capturing or playback of audio. Applet code is not allowed to write native files by default. The .java.policy file must 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:

SoundCapture

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

Red (vogel)

Constructor Summary

Constructors

Constructor	Description
SoundWriter(java.lang.String fileName, float sampleRate, int bitsPerSample, int channels, int putSamplesArraySize)	Construct a sound writer object with the specified name.

Method Summary

Modifier and Type	Method	Description
void	closeFile()	Open a the file specified in the constructor for writing, write the accumulated audio samples (obtained via putSamples()) to the file specified in the constructor, and close the file.
void	putSamples(double[][] putSamplesArray)	Append the audio data contained in putSamplesArray to an internal array.

Methods inherited from class java.lang.Object

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

Constructor Detail

SoundWriter

public SoundWriter(java.lang.String fileName,
                   float sampleRate,
                   int bitsPerSample,
                   int channels,
                   int putSamplesArraySize)

Construct a sound writer object with the specified name. Valid sound file formats are WAVE (.wav), AIFF (.aif, .aiff), AU (.au). The file format is automatically determined from the file extension.

Parameters:

fileName - The file name to create. If the file already exists, overwrite it. Valid sound file formats are WAVE (.wav), AIFF (.aif, .aiff), AU (.au). The file format to write is determined automatically from the file extension.

sampleRate - Sample rate in Hz. Must be in the range: 8000 to 48000.

bitsPerSample - Number of bits per sample (valid choices are 8 or 16).

channels - Number of audio channels. 1 for mono, 2 for stereo.

putSamplesArraySize - Size of the array parameter of putSamples(). There is no restriction on the value of this parameter, but typical values are 64-2024.

Method Detail

putSamples

public void putSamples(double[][] putSamplesArray)
                throws java.lang.IllegalStateException

Append the audio data contained in putSamplesArray to an internal array. The audio samples in this array will be written to the sound file specified in the constructor when the closeFile() method is invoked.

The samples should be in the range (-1, 1). Samples that are outside this range will be hard-clipped so that they fall within this range.

Parameters:

putSamplesArray - A two dimensional array containing the samples to play or write to a file. 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, putSamplesArray[n][m] contains the (m+1)th sample of the (n+1)th channel. putSamplesArray should be a rectangular array such that putSamplesArray.length() gives the number of channels and putSamplesArray[n].length() is equal to putSamplesSize, for all channels n. An exception will occur if this is not the case.

Throws:

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

closeFile

public void closeFile()
               throws java.io.IOException

Open a the file specified in the constructor for writing, write the accumulated audio samples (obtained via putSamples()) to the file specified in the constructor, and close the file. This method should be called when no more calls to putSamples() are required. An exception will occur if putSamples() is called after this method is invoked.

Throws:

java.io.IOException - If there is a problem closing the audio resources, or if the "write audio data to file" constructor was used and the sound file has an unsupported format.