Object
- edu.princeton.cs.algs4.StdAudio

```
public final class StdAudio
extends Object
```
The StdAudio class provides static methods 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.
See StdAudioStereo for a version that supports stereo audio (separate left and right channels).
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 audio 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. When reading files, StdAudio converts to a sammpling rate of 44,100 Hz, with 16 bits per sample.
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 playInBackground().
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 Description

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

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static void`	`drain()`	Sends any queued samples to the sound card.
`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 audio samples 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 java.lang.Object
clone, equals, 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. The file extension must be either .wav, .au, or .aiff.
    
    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 file extension must be either .wav, .au, or .aiff.
    
    Parameters:
    
    filename - the name of the audio file
    
    Returns:
    
    the array of samples
  - save
```
public static void save(String filename,
                        double[] samples)
```
    Saves the audio samples as an audio file (using WAV, AU, or AIFF format). The file extension must be either .wav, .au, or .aiff. The format uses a sampling rate of 44,100 Hz, 16-bit audio, monaural, 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 is the empty string
    
    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. The file extension must be either .wav, .au, or .aiff.
    
    Parameters:
    
    filename - the name of the audio file
    
    Throws:
    
    IllegalArgumentException - if unable to play filename
    
    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)

Class StdAudio

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SAMPLE_RATE

Method Detail

drain

play

play

play

read

save

stopInBackground

playInBackground

startRecording

stopRecording

main