Class 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:

    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:

    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:

    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).

    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).

    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:

    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 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.

    • 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

      • 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)