Class StdAudio

Object

StdAudio

public final class StdAudio
extends Object

Overview. The StdAudio class provides a basic capability for playing, reading, and saving audio. It uses a simple audio model that allows you to send one sample to the sound card at a time. Each sample is a real number between –1.0 and +1.0. The samples are played in real time using a sampling rate of 44,100 Hz. In addition to playing individual samples, standard audio supports reading, writing, and playing audio files in a variety of standard formats.

Getting started. To use this class, you must have StdAudio in your Java classpath. Here are three possible ways to do this:

• If you ran our autoinstaller, use the commands javac-introcs and java-introcs (or javac-algs4 and java-algs4) when compiling and executing. These commands add stdlib.jar (or algs4.jar) to the Java classpath, which provides access to StdAudio.
• Download stdlib.jar (or algs4.jar) and add it to the Java classpath.
• Download StdAudio.java and put it in the working directory.

As a test, cut-and-paste the following short program into your editor:

   public class TestStdAudio {
       public static void main(String[] args) {
           double freq = 440.0;
           for (int i = 0; i < StdAudio.SAMPLE_RATE; i++) {
               double sample = 0.5 * Math.sin(2 * Math.PI * freq * i / StdAudio.SAMPLE_RATE);
               StdAudio.play(sample);
           }
           StdAudio.drain();
       }
   }
  

If you compile and execute the program, you should hear a pure tone whose frequency is concert A (440 Hz).

Playing audio samples. You can use the following two methods to play individual audio samples:

• play(double sample)
• play(double[] samples)

Each method sends the specified sample (or samples) to the sound card. The individual samples are real numbers between –1.0 and +1.0. If a sample is outside this range, it will be clipped (rounded to –1.0 or +1.0). The samples are played in real time using a sampling rate of 44,100 Hz.

Playing audio files. You can use the following method to play an audio file:

• play(String filename)

It plays an audio file (in WAVE, AU, AIFF, or MIDI format) and does not return until the audio file is finished playing. This can produce particularly striking programs with minimal code. For example, the following code fragment plays a drum loop:

   while (true) {
       StdAudio.play("BassDrum.wav");
       StdAudio.play("SnareDrum.wav");
   }
  

The individual audio files (such as BassDrum.wav and SnareDrum.wav) must be accessible to Java, typically by being in the same directory as the .class file.

Reading and writing audio files. You can read and write audio files using the following two methods:

• read(String filename)
• save(String filename, double[] samples)

The first method reads audio samples from an audio file (in WAVE, AU, AIFF, or MIDI format) and returns them as a double array with values between –1.0 and +1.0. The second method saves the samples in the specified double array to an audio file (in WAVE, AU, or AIFF format).

Audio file formats. StdAudio relies on the Java Media Framework for reading, writing, and playing audio files. You should be able to read or play files in WAVE, AU, AIFF, and MIDI formats and save them to WAVE, AU, and AIFF formats. The file extensions corresponding to WAVE, AU, AIFF, and MIDI files are .wav, .au, .aiff, and .midi, respectively. Some systems support additional audio file formats, but probably not MP3 or M4A.

The Java Media Framework supports a variety of different audio data formats, which includes

• the sampling rate (e.g., 44,100 Hz);
• the number of bits per sample per channel (e.g., 8-bit or 16-bit);
• the number of channels (e.g., monaural or stereo);
• the byte ordering (e.g., little endian or big endian); and
• the encoding scheme (typically linear PCM).

When saving files, StdAudio uses a sampling rate of 44,100 Hz, 16 bits per sample, monaural audio, little endian, and linear PCM encoding.

Recording audio. You can use the following methods to record audio samples that are played as a result of calls to play(double sample) or play(double[] samples).

• startRecording()
• stopRecording()

The method startRecording() begins recording audio. The method stopRecording() stops recording and returns the recorded samples as an array of doubles.

StdAudio does not currently support recording audio that calls either play(String filename) or playInBackground(String filename), as these may use different data formats, such as 8-bit and stereo.

Playing audio files in a background thread. You can use the following methods to play an audio file in a background thread (e.g., as a background score in your program).

• playInBackground(String filename)
• stopInBackground()

Each call to the first method plays the specified sound in a separate background thread. Unlike with the play() methods, your program will not wait for the samples to finish playing before continuing. It supports playing an audio file in WAVE, AU, AIFF, or MIDI format. It is possible to play multiple audio files simultaneously (in separate background threads). The second method stops the playing of all audio in background threads.

Draining standard audio. On some systems, your Java program may terminate before all of the samples have been sent to the sound card. To prevent this, it is recommend that you call the following method to indicate that you are done using standard audio:

• drain()

The method drains any samples queued to the sound card that have not yet been sent to the sound card.

Reference. For additional documentation, see Section 1.5 of Computer Science: An Interdisciplinary Approach by Robert Sedgewick and Kevin Wayne.

Author:

Robert Sedgewick, Kevin Wayne

Field Summary

Fields

Modifier and Type	Field and Description
static int	SAMPLE_RATE The sample rate: 44,100 Hz for CD quality audio.

Method Summary

Modifier and Type	Method and Description
static void	drain() Sends any queued samples to the sound card.
static void	loopInBackground(String filename) Deprecated. to be removed in a future update, as it doesn't interact well with playInBackground(String filename) or stopInBackground().
static void	main(String[] args) Test client - plays some sound files and concert A.
static void	play(double sample) Writes one sample (between –1.0 and +1.0) to standard audio.
static void	play(double[] samples) Writes the array of samples (between –1.0 and +1.0) to standard audio.
static void	play(String filename) Plays an audio file (in WAVE, AU, AIFF, or MIDI format) and waits for it to finish.
static void	playInBackground(String filename) Plays an audio file (in WAVE, AU, AIFF, or MIDI format) in its own background thread.
static double[]	read(String filename) Reads audio samples from a file (in WAVE, AU, AIFF, or MIDI format) and returns them as a double array with values between –1.0 and +1.0.
static void	save(String filename, double[] samples) Saves the double array as an audio file (using WAV, AU, or AIFF format).
static void	startRecording() Turns on audio recording.
static void	stopInBackground() Stops the playing of all audio files in background threads.
static double[]	stopRecording() Turns off audio recording and returns the recorded samples.

Methods inherited from class Object

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

Field Detail

SAMPLE_RATE

public static final int SAMPLE_RATE

The sample rate: 44,100 Hz for CD quality audio.

See Also:

Constant Field Values

Method Detail

drain

public static void drain()

Sends any queued samples to the sound card.

play

public static void play(double sample)

Writes one sample (between –1.0 and +1.0) to standard audio. If the sample is outside the range, it will be clipped (rounded to –1.0 or +1.0).

Parameters:

sample - the sample to play

Throws:

IllegalArgumentException - if the sample is Double.NaN

play

public static void play(double[] samples)

Writes the array of samples (between –1.0 and +1.0) to standard audio. If a sample is outside the range, it will be clipped.

Parameters:

samples - the array of samples to play

Throws:

IllegalArgumentException - if any sample is Double.NaN

IllegalArgumentException - if samples is null

play

public static void play(String filename)

Plays an audio file (in WAVE, AU, AIFF, or MIDI format) and waits for it to finish.

Parameters:

filename - the name of the audio file

Throws:

IllegalArgumentException - if unable to play filename

IllegalArgumentException - if filename is null

read

public static double[] read(String filename)

Reads audio samples from a file (in WAVE, AU, AIFF, or MIDI format) and returns them as a double array with values between –1.0 and +1.0. The sound format must use 16-bit audio data with a sampling rate of 44,100. The sound format can be either monoaural or stereo, and the bytes can be stored in either little endian or big endian order.

Parameters:

filename - the name of the audio file

Returns:

the array of samples

save

public static void save(String filename,
                        double[] samples)

Saves the double array as an audio file (using WAV, AU, or AIFF format). The file extension type must be either .wav, .au, or .aiff. The format uses a sampling rate of 44,100 Hz, 16-bit audio, mono, signed PCM, ands little Endian.

Parameters:

filename - the name of the audio file

samples - the array of samples

Throws:

IllegalArgumentException - if unable to save filename

IllegalArgumentException - if samples is null

IllegalArgumentException - if filename is null

IllegalArgumentException - if filename extension is not .wav, .au, or .aiff.

stopInBackground

public static void stopInBackground()

Stops the playing of all audio files in background threads.

playInBackground

public static void playInBackground(String filename)

Plays an audio file (in WAVE, AU, AIFF, or MIDI format) in its own background thread. Multiple audio files can be played simultaneously.

Parameters:

filename - the name of the audio file

Throws:

IllegalArgumentException - if unable to play filename

IllegalArgumentException - if filename is null

loopInBackground

@Deprecated
public static void loopInBackground(String filename)

Deprecated. to be removed in a future update, as it doesn't interact well with playInBackground(String filename) or stopInBackground().

Loops an audio file (in WAVE, AU, AIFF, or MIDI format) in its own background thread.

Parameters:

filename - the name of the audio file

Throws:

IllegalArgumentException - if filename is null

startRecording

public static void startRecording()

Turns on audio recording.

stopRecording

public static double[] stopRecording()

Turns off audio recording and returns the recorded samples.

Returns:

the array of recorded samples

main

public static void main(String[] args)

Test client - plays some sound files and concert A.

Parameters:

args - the command-line arguments (none should be specified)